@markuplint/ml-core 4.13.2 → 5.0.0-alpha.0

package/docs/ml-dom/helpers.ja.md

@@ -0,0 +1,203 @@
+# ヘルパーとユーティリティ
+
+## ヘルパー関数
+
+### createNode()
+
+**ソース:** `src/ml-dom/helper/create-node.ts`
+
+AST ノード型を対応する MLDOM コンストラクタにディスパッチするファクトリ関数です。
+
+| AST `type` フィールド             | MLDOM クラス                                                      | `nodeType` |
+| --------------------------------- | ----------------------------------------------------------------- | ---------- |
+| `'doctype'`                       | `MLDocumentType`                                                  | `10`       |
+| `'starttag'`                      | `MLElement`                                                       | `1`        |
+| `'comment'`                       | `MLComment`                                                       | `8`        |
+| `'text'`                          | `MLText`                                                          | `3`        |
+| `'psblock'`                       | `MLBlock`                                                         | `101`      |
+| `'invalid'`（`kind: 'starttag'`） | `MLElement`（`x-invalid`、`elementType: 'web-component'` として） | `1`        |
+| `'invalid'`（その他の kind）      | `MLText`                                                          | `3`        |
+
+**注:** `'endtag'` は `createNode()` を通過しません -- ドキュメントのコンストラクション中にスキップされます。`MLElement` は `pairNode` 参照から内部的に `MLElementCloseTag` を作成します。`MLASTAttr` は `MLElement` によって処理され、要素の `attributes` 配列から `MLAttr` インスタンスを作成します。
+
+### ウォーカー
+
+**ソース:** `src/ml-dom/helper/walkers.ts`
+
+#### `syncWalk(nodeList, walker)`
+
+同期的な深さ優先ツリー走査です。`nodeList` の各ノードに対して：
+
+- ノードが `ELEMENT_NODE` または `MARKUPLINT_PREPROCESSOR_BLOCK` の場合：まず子を再帰的に走査し、**それから**ノードに対して walker を呼び出す（後順走査）
+
+#### `sequentialWalker(list, walker)`
+
+逐次的な非同期走査です。walker が同期か非同期かに関わらず、walker が一度に1つずつ実行されることを保証します。内部のプロミスチェーンを使って逐次実行します。
+
+### accname
+
+**ソース:** `src/ml-dom/helper/accname.ts`
+
+#### `getAccname(element, version)`
+
+WAI-ARIA アルゴリズムに従って要素のアクセシブル名を計算します：
+
+1. `@markuplint/ml-spec` の `get()` 関数で直接計算を試みる（`aria-label`、`aria-labelledby` などを処理）
+2. 要素が ARIA 設定を持つ pretender コンテキストを持つ場合 → `getAccnameFromPretender()` を使用する：
+   - pretender 設定から `aria.name` プロパティを読み取る
+   - `name` が `fromAttr` を持つオブジェクトの場合 → 元の要素から指定された属性の値を読み取る
+3. 要素が `aria-hidden="true"` または `hidden` 属性を持つ場合 → 空文字列を返す
+4. ロールが `accessibleNameFromContent` をサポートする場合 → 子のテキストコンテンツを再帰的に連結する
+5. それ以外の場合 → 空文字列を返す
+
+### getIndent
+
+**ソース:** `src/ml-dom/helper/get-indent.ts`
+
+#### `getIndent(node)`（非推奨）
+
+隣接するテキストノードの空白を調べて、ノードの前のインデントを解析します。
+
+`MLDOMIndentation` を返します：
+
+| プロパティ/メソッド | 型                                      | 説明                                                                         |
+| ------------------- | --------------------------------------- | ---------------------------------------------------------------------------- |
+| `raw`               | `string`                                | インデント文字列                                                             |
+| `type`              | `'tab' \| 'space' \| 'mixed' \| 'none'` | インデントの種類                                                             |
+| `width`             | `number`                                | インデントの文字数                                                           |
+| `line`              | `number`                                | インデントが発生する行番号                                                   |
+| `fix(raw)`          | メソッド                                | ソーステキストノード内の対応する行のインデントを変更してインデントを置換する |
+
+`fix()` メソッドはテキストノードの `raw` を改行で分割し、対象行のインデントを置換し、再結合した文字列でテキストノードの `fix()` を呼び出します。
+
+## 補助クラス
+
+### MLNamedNodeMap
+
+**ソース:** `src/ml-dom/node/named-node-map.ts`
+
+`Array<MLAttr>` を継承し、DOM `NamedNodeMap` インターフェースを実装します。`MLElement.attributes` で使用されます。
+
+- **重複排除**: 各属性名の最初の出現のみが保持される
+- **`getNamedItem(qualifiedName)`**: 大文字小文字を区別する名前検索。`MLAttr | null` を返す
+- **`item(index)`**: インデックスベースのアクセス
+- ミューテーションメソッド（`setNamedItem`、`removeNamedItem` など）は `UnexpectedCallError` をスローする
+
+#### `toNamedNodeMap(nodes)`
+
+`MLAttr` の読み取り専用配列から `MLNamedNodeMap` を作成するヘルパー関数です。
+
+### MLDomTokenList
+
+**ソース:** `src/ml-dom/node/dom-token-list.ts`
+
+`Array<string>` を継承し、DOM `DOMTokenList` インターフェースを実装します。スペース区切りの属性値（例：`class`）に使用されます。
+
+| プロパティ/メソッド | 型               | 説明                                           |
+| ------------------- | ---------------- | ---------------------------------------------- |
+| `value`             | `string`         | 元の属性値文字列                               |
+| `contains(token)`   | `boolean`        | セットベースの高速なトークン存在チェック       |
+| `allTokens()`       | `Scope[]`        | 各トークンの位置情報（`Scope`）を返す          |
+| `pick(token)`       | `Scope \| null`  | 特定のトークンの位置情報を返す                 |
+| `add(...tokens)`    | `void`           | トークンを追加する（基となる属性値を変更する） |
+| `item(index)`       | `string \| null` | インデックスベースのトークンアクセス           |
+| `forEach(callback)` | `void`           | コールバックでトークンを反復する               |
+| `toString()`        | `string`         | 元の `value` 文字列を返す                      |
+
+ミューテーションメソッド（`remove`、`replace`、`toggle`、`supports`）は `UnexpectedCallError` をスローします。
+
+`Scope` オブジェクトには、属性値内の各トークンの正確なソース位置として `startOffset`、`endOffset`、`startLine`、`startCol`、`endLine`、`endCol` が含まれます。
+
+## 型ユーティリティ
+
+**ソース:** `src/ml-dom/node/types.ts`
+
+### MappedNode
+
+TypeScript の型レベルで AST ノード型を対応する MLDOM ラッパー型にマッピングします：
+
+```typescript
+type MappedNode<N, T, O> = N extends MLASTElement
+  ? MLElement<T, O>
+  : N extends MLASTComment
+    ? MLComment<T, O>
+    : N extends MLASTText
+      ? MLText<T, O>
+      : N extends MLASTDoctype
+        ? MLDocumentType<T, O>
+        : N extends MLASTPreprocessorSpecificBlock
+          ? MLBlock<T, O>
+          : N extends MLASTAttr
+            ? MLAttr<T, O>
+            : N extends MLASTInvalid
+              ? MLText<T, O>
+              : N extends MLASTToken
+                ? MLToken
+                : never;
+```
+
+### NodeTypeOf
+
+数値のノード型定数を MLDOM クラス型に解決し、`is()` 型ガードを有効にします：
+
+```typescript
+type NodeTypeOf<NT, T, O> = NT extends 1
+  ? MLElement<T, O> // ELEMENT_NODE
+  : NT extends 8
+    ? MLComment<T, O> // COMMENT_NODE
+    : NT extends 3
+      ? MLText<T, O> // TEXT_NODE
+      : NT extends 9
+        ? MLDocument<T, O> // DOCUMENT_NODE
+        : NT extends 10
+          ? MLDocumentType<T, O> // DOCUMENT_TYPE_NODE
+          : NT extends 11
+            ? MLDocumentFragment<T, O> // DOCUMENT_FRAGMENT_NODE
+            : NT extends 101
+              ? MLBlock<T, O> // MARKUPLINT_PREPROCESSOR_BLOCK
+              : NT extends 2
+                ? MLAttr<T, O> // ATTRIBUTE_NODE
+                : never;
+```
+
+### AccessibilityProperties
+
+`MLDocument.getAccessibilityProp()` が返す計算済みアクセシビリティプロパティ：
+
+```typescript
+type AccessibilityProperties =
+  | {
+      unknown: false;
+      exposedToTree: boolean;
+      role?: string;
+      name?: string | { unknown: true };
+      nameRequired?: boolean;
+      nameProhibited?: boolean;
+      focusable?: boolean;
+      props?: Record<string, { value: string | null; required: boolean }>;
+    }
+  | {
+      unknown: true;
+    };
+```
+
+### PretenderContext
+
+pretender システムのコンテキスト：
+
+```typescript
+// 別の要素として振る舞う要素
+type PretenderContextPretender<N, T, O> = {
+  readonly type: 'pretender';
+  readonly as: N; // 振る舞い先の仮想 MLElement
+  readonly aria?: PretenderARIA;
+};
+
+// 元の要素を指す仮想要素
+type PretenderContextPretended<N, T, O> = {
+  readonly type: 'origin';
+  readonly origin: N; // 元の MLElement
+};
+
+type PretenderContext<N, T, O> = PretenderContextPretender<N, T, O> | PretenderContextPretended<N, T, O>;
+```

package/docs/ml-dom/helpers.md

@@ -0,0 +1,203 @@
+# Helpers & Utilities
+
+## Helper Functions
+
+### createNode()
+
+**Source:** `src/ml-dom/helper/create-node.ts`
+
+Factory function that dispatches AST node types to their corresponding MLDOM constructors.
+
+| AST `type` Field                 | MLDOM Class                                                  | `nodeType` |
+| -------------------------------- | ------------------------------------------------------------ | ---------- |
+| `'doctype'`                      | `MLDocumentType`                                             | `10`       |
+| `'starttag'`                     | `MLElement`                                                  | `1`        |
+| `'comment'`                      | `MLComment`                                                  | `8`        |
+| `'text'`                         | `MLText`                                                     | `3`        |
+| `'psblock'`                      | `MLBlock`                                                    | `101`      |
+| `'invalid'` (`kind: 'starttag'`) | `MLElement` (as `x-invalid`, `elementType: 'web-component'`) | `1`        |
+| `'invalid'` (other kind)         | `MLText`                                                     | `3`        |
+
+**Note:** `'endtag'` is not passed through `createNode()` -- it is skipped during document construction. `MLElement` creates `MLElementCloseTag` internally from its `pairNode` reference. `MLASTAttr` is handled by `MLElement` which creates `MLAttr` instances from the element's `attributes` array.
+
+### Walkers
+
+**Source:** `src/ml-dom/helper/walkers.ts`
+
+#### `syncWalk(nodeList, walker)`
+
+Synchronous depth-first tree walking. For each node in `nodeList`:
+
+- If the node is an `ELEMENT_NODE` or `MARKUPLINT_PREPROCESSOR_BLOCK`: recursively walk its children first, **then** call the walker on the node (post-order traversal)
+
+#### `sequentialWalker(list, walker)`
+
+Sequential async walking. Ensures walkers execute one at a time regardless of whether the walker is sync or async. Uses an internal promise chain for sequential execution.
+
+### accname
+
+**Source:** `src/ml-dom/helper/accname.ts`
+
+#### `getAccname(element, version)`
+
+Computes the accessible name for an element following WAI-ARIA algorithms:
+
+1. Attempt direct computation via `@markuplint/ml-spec`'s `get()` function (handles `aria-label`, `aria-labelledby`, etc.)
+2. If the element has a pretender context with ARIA settings → use `getAccnameFromPretender()`:
+   - Reads the `aria.name` property from the pretender config
+   - If `name` is an object with `fromAttr` → reads the specified attribute's value from the original element
+3. If the element has `aria-hidden="true"` or `hidden` attribute → return empty string
+4. If the role supports `accessibleNameFromContent` → recursively concatenate child text content
+5. Otherwise → return empty string
+
+### getIndent
+
+**Source:** `src/ml-dom/helper/get-indent.ts`
+
+#### `getIndent(node)` (deprecated)
+
+Analyzes indentation preceding a node by examining whitespace in adjacent text nodes.
+
+Returns `MLDOMIndentation`:
+
+| Property/Method | Type                                    | Description                                                                          |
+| --------------- | --------------------------------------- | ------------------------------------------------------------------------------------ |
+| `raw`           | `string`                                | The indentation string                                                               |
+| `type`          | `'tab' \| 'space' \| 'mixed' \| 'none'` | Indentation type                                                                     |
+| `width`         | `number`                                | Character count of indentation                                                       |
+| `line`          | `number`                                | Line number where indentation occurs                                                 |
+| `fix(raw)`      | Method                                  | Replaces the indentation by modifying the corresponding line in the source text node |
+
+The `fix()` method splits the text node's `raw` by newlines, replaces the indentation on the target line, and calls `fix()` on the text node with the rejoined string.
+
+## Supplementary Classes
+
+### MLNamedNodeMap
+
+**Source:** `src/ml-dom/node/named-node-map.ts`
+
+Extends `Array<MLAttr>` and implements the DOM `NamedNodeMap` interface. Used by `MLElement.attributes`.
+
+- **Deduplication**: Only the first occurrence of each attribute name is kept
+- **`getNamedItem(qualifiedName)`**: Case-sensitive name lookup, returns `MLAttr | null`
+- **`item(index)`**: Index-based access
+- Mutation methods (`setNamedItem`, `removeNamedItem`, etc.) throw `UnexpectedCallError`
+
+#### `toNamedNodeMap(nodes)`
+
+Helper function that creates an `MLNamedNodeMap` from a readonly array of `MLAttr` instances.
+
+### MLDomTokenList
+
+**Source:** `src/ml-dom/node/dom-token-list.ts`
+
+Extends `Array<string>` and implements the DOM `DOMTokenList` interface. Used for space-separated attribute values (e.g., `class`).
+
+| Property/Method     | Type             | Description                                            |
+| ------------------- | ---------------- | ------------------------------------------------------ |
+| `value`             | `string`         | The original attribute value string                    |
+| `contains(token)`   | `boolean`        | Set-based fast token existence check                   |
+| `allTokens()`       | `Scope[]`        | Returns position information (`Scope`) for each token  |
+| `pick(token)`       | `Scope \| null`  | Returns position info for a specific token             |
+| `add(...tokens)`    | `void`           | Adds tokens (modifies the underlying attribute values) |
+| `item(index)`       | `string \| null` | Index-based token access                               |
+| `forEach(callback)` | `void`           | Iterates tokens with callback                          |
+| `toString()`        | `string`         | Returns the original `value` string                    |
+
+Mutation methods (`remove`, `replace`, `toggle`, `supports`) throw `UnexpectedCallError`.
+
+The `Scope` object contains `startOffset`, `endOffset`, `startLine`, `startCol`, `endLine`, `endCol` for precise source location of each token within the attribute value.
+
+## Type Utilities
+
+**Source:** `src/ml-dom/node/types.ts`
+
+### MappedNode
+
+Maps an AST node type to its corresponding MLDOM wrapper type at the TypeScript type level:
+
+```typescript
+type MappedNode<N, T, O> = N extends MLASTElement
+  ? MLElement<T, O>
+  : N extends MLASTComment
+    ? MLComment<T, O>
+    : N extends MLASTText
+      ? MLText<T, O>
+      : N extends MLASTDoctype
+        ? MLDocumentType<T, O>
+        : N extends MLASTPreprocessorSpecificBlock
+          ? MLBlock<T, O>
+          : N extends MLASTAttr
+            ? MLAttr<T, O>
+            : N extends MLASTInvalid
+              ? MLText<T, O>
+              : N extends MLASTToken
+                ? MLToken
+                : never;
+```
+
+### NodeTypeOf
+
+Resolves a numeric node type constant to its MLDOM class type, enabling the `is()` type guard:
+
+```typescript
+type NodeTypeOf<NT, T, O> = NT extends 1
+  ? MLElement<T, O> // ELEMENT_NODE
+  : NT extends 8
+    ? MLComment<T, O> // COMMENT_NODE
+    : NT extends 3
+      ? MLText<T, O> // TEXT_NODE
+      : NT extends 9
+        ? MLDocument<T, O> // DOCUMENT_NODE
+        : NT extends 10
+          ? MLDocumentType<T, O> // DOCUMENT_TYPE_NODE
+          : NT extends 11
+            ? MLDocumentFragment<T, O> // DOCUMENT_FRAGMENT_NODE
+            : NT extends 101
+              ? MLBlock<T, O> // MARKUPLINT_PREPROCESSOR_BLOCK
+              : NT extends 2
+                ? MLAttr<T, O> // ATTRIBUTE_NODE
+                : never;
+```
+
+### AccessibilityProperties
+
+Computed accessibility properties returned by `MLDocument.getAccessibilityProp()`:
+
+```typescript
+type AccessibilityProperties =
+  | {
+      unknown: false;
+      exposedToTree: boolean;
+      role?: string;
+      name?: string | { unknown: true };
+      nameRequired?: boolean;
+      nameProhibited?: boolean;
+      focusable?: boolean;
+      props?: Record<string, { value: string | null; required: boolean }>;
+    }
+  | {
+      unknown: true;
+    };
+```
+
+### PretenderContext
+
+Context for the pretender system:
+
+```typescript
+// Element pretending to be another element
+type PretenderContextPretender<N, T, O> = {
+  readonly type: 'pretender';
+  readonly as: N; // The virtual MLElement being pretended as
+  readonly aria?: PretenderARIA;
+};
+
+// Virtual element pointing back to the original
+type PretenderContextPretended<N, T, O> = {
+  readonly type: 'origin';
+  readonly origin: N; // The original MLElement
+};
+
+type PretenderContext<N, T, O> = PretenderContextPretender<N, T, O> | PretenderContextPretended<N, T, O>;
+```

package/docs/ml-dom/node.ja.md

@@ -0,0 +1,199 @@
+# MLNode / MLParentNode
+
+## MLNode
+
+**ソース:** `src/ml-dom/node/node.ts`
+
+すべての markuplint DOM ノードラッパーの抽象基底クラスです。`MLToken` を継承し、DOM `Node` インターフェース準拠、ツリー走査、ルール設定アクセス、子ノード管理の機能を追加します。
+
+### ノード型定数
+
+| 定数                            | 値    | DOM Standard              |
+| ------------------------------- | ----- | ------------------------- |
+| `ELEMENT_NODE`                  | `1`   | はい                      |
+| `ATTRIBUTE_NODE`                | `2`   | はい                      |
+| `TEXT_NODE`                     | `3`   | はい                      |
+| `CDATA_SECTION_NODE`            | `4`   | はい                      |
+| `PROCESSING_INSTRUCTION_NODE`   | `7`   | はい                      |
+| `COMMENT_NODE`                  | `8`   | はい                      |
+| `DOCUMENT_NODE`                 | `9`   | はい                      |
+| `DOCUMENT_TYPE_NODE`            | `10`  | はい                      |
+| `DOCUMENT_FRAGMENT_NODE`        | `11`  | はい                      |
+| `MARKUPLINT_PREPROCESSOR_BLOCK` | `101` | いいえ（markuplint 拡張） |
+
+### ツリー構造プロパティ
+
+| プロパティ              | 型                                                                 | 説明                                                                              |
+| ----------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
+| `parentNode`            | `MLDocument \| MLDocumentFragment \| MLElement \| null`            | DOM 準拠の親。透過的な `MLBlock` の親はスキップされる                             |
+| `parentElement`         | `MLElement \| null`                                                | 最も近い `MLElement` である祖先                                                   |
+| `syntacticalParentNode` | `MLDocument \| MLDocumentFragment \| MLElement \| MLBlock \| null` | `MLBlock` ノードを含む構文上の親                                                  |
+| `childNodes`            | `NodeListOf<MLChildNode>`                                          | 子ノード（Element, Text, Comment, Block）。フラグメントの子はインライン展開される |
+| `firstChild`            | `MLChildNode \| null`                                              | 最初の子ノード                                                                    |
+| `lastChild`             | `MLChildNode \| null`                                              | 最後の子ノード                                                                    |
+| `nextSibling`           | `MLChildNode \| null`                                              | 同じ `parentNode` を持つ次の兄弟ノード                                            |
+| `previousSibling`       | `MLChildNode \| null`                                              | 同じ `parentNode` を持つ前の兄弟ノード                                            |
+| `nextNode`              | `MLNode \| null`                                                   | 構文上の兄弟リスト内の次のノード（`syntacticalParentNode.childNodes` から）       |
+| `prevNode`              | `MLNode \| null`                                                   | 構文上の兄弟リスト内の前のノード                                                  |
+| `prevToken`             | `MLNode \| null`                                                   | ドキュメント順 `nodeList` 内の前のノード（省略された要素はスキップ）              |
+| `ownerDocument`         | `any`                                                              | 所属するドキュメント（DOM 互換、`any` 型）                                        |
+| `ownerMLDocument`       | `MLDocument<T, O>`                                                 | 適切なジェネリクス型を持つ所属ドキュメント                                        |
+| `isFragment`            | `boolean`                                                          | このノードがフラグメントとして動作するかどうか                                    |
+
+#### `nextNode`/`prevNode` と `nextSibling`/`previousSibling` の違い
+
+この2組のプロパティは異なる目的に使用されます：
+
+- **`nextNode`/`prevNode`**: `syntacticalParentNode.childNodes`（構文上の親がない場合は `nodeList`）の構文上の兄弟リストを走査します。`MLBlock` ノードを含み、AST レベルで動作します。
+- **`nextSibling`/`previousSibling`**: 同じ DOM `parentNode` を共有する兄弟を走査します。`parentNode` が異なるノード（例：非透過ブロック内のノード）はスキップされます。
+
+#### `prevToken` と省略された要素
+
+`prevToken` はドキュメント順の `nodeList` を走査しますが、**省略された（ゴースト）要素をスキップ**します。省略された要素は対応するソーストークンを持たないため、それらを含めるとオフセット計算が壊れます。これはインデント解析やソース再構築にとって重要です。
+
+### `childNodes` とフラグメント展開
+
+子ノードが `isFragment === true` を持つ場合、その子ノード自身の子が親の `childNodes` にインライン展開されます：
+
+```jsx
+// JSX フラグメント
+<div>
+  <>
+    {' '}
+    {/* isFragment = true */}
+    <p>A</p>
+    <p>B</p>
+  </>
+  <p>C</p>
+</div>
+```
+
+`div.childNodes` は `[<p>A</p>, <p>B</p>, <p>C</p>]` を返します -- フラグメントラッパーは透過的です。
+
+### `parentNode` と MLBlock の透過性
+
+`parentNode` ゲッターは `MLBlock` の透過性を処理します：
+
+1. `syntacticalParentNode` を取得
+2. 親が `isTransparent === true` の `MLBlock` の場合：ブロックの `parentNode` を返す（再帰的にスキップ）
+3. 親が `isTransparent === false` の `MLBlock` の場合：`null` を返す（DOM の観点からノードは「孤立」している）
+4. 親がフラグメント `MLDocument`（つまり `isFragment === true`）の場合：`null` を返す
+5. それ以外の場合：親をそのまま返す
+
+| シナリオ                                    | `syntacticalParentNode` | `parentNode`                |
+| ------------------------------------------- | ----------------------- | --------------------------- |
+| `<body>` 内の `<div>`                       | `<body>`                | `<body>`                    |
+| `<div>` 内の Pug `if` ブロック内の `<span>` | `#ml-block`             | `<div>`（透過的にスキップ） |
+| 非透過ブロック内の `<span>`                 | `#ml-block`             | `null`                      |
+| フラグメントドキュメントのトップレベル      | `#document`             | `null`                      |
+
+```pug
+//- Pug の例
+div
+  if foo
+    span
+    //- syntacticalParentNode: #ml-block
+    //- parentNode: <div>  (ブロックは透過的、スキップされる)
+```
+
+### `conditionalChildNodes()` -- 条件分岐パターン生成
+
+テンプレートエンジンの条件分岐から可能なすべての子ノードの組み合わせを生成します。これは `permitted-contents` などのルールが、すべてのレンダリングパスに対してコンテンツモデルを検証するために使用されます。
+
+#### アルゴリズム
+
+1. `childNodes` を順番に走査する
+2. `MLBlock` に遭遇した場合、その `blockBehavior?.type` から分岐 `mode` を決定する：
+   - `'if'` または `'if:elseif'` → mode `'if'`
+   - `'switch:case'` → mode `'switch'`
+   - `'if:else'`、`'each'`、`'each:empty'`、`'switch:default'`、`'await'`、`'await:catch'`、`'await:then'` → 現在のモードを継続（新しいモードは設定されない）
+   - その他の型 → スキップ（条件分岐ではない）
+3. ブロックに対して再帰的に `conditionalChildNodes()` を呼び出し、サブパターンを取得する
+4. 分岐を収集する。非ブロックの子に到達したら、現在の分岐グループを閉じる
+5. 空白のみのテキストノードはスキップされる
+6. `'if'`、`'switch'` モードの場合：「空の分岐」（何もレンダリングされないケース）を表す `null` センチネルが追加される
+7. 収集した分岐を `branchesToPatterns()` に渡し、すべての組み合わせの直積を生成する
+
+#### 例
+
+```html
+<ul>
+  {% if cond %}
+  <li>A</li>
+  {% else %}
+  <li>B</li>
+  {% endif %}
+  <li>C</li>
+</ul>
+```
+
+`ul.conditionalChildNodes()` は以下を返します：
+
+- パターン 1: `[<li>A</li>, <li>C</li>]`
+- パターン 2: `[<li>B</li>, <li>C</li>]`
+
+`permitted-contents` ルールは**すべての**パターンを検査して妥当性を確認します。
+
+### `findSubsequentNodes(selector?)`
+
+ドキュメント順でこのノードの後に出現するノードを収集します：
+
+1. `ownerMLDocument.nodeList` を反復する
+2. `endOffset <= this.endOffset` のノードをスキップする
+3. 子孫ノードをスキップする（`this.contains(node)` で判定）
+4. `selector` が指定されている場合：CSS セレクタにマッチする要素のみを含める
+5. `selector` が未指定の場合：すべての後続 `MLChildNode` インスタンス（Element, Text, Comment, Block）を含める
+
+### ルールプロパティ
+
+| プロパティ | 型                        | 説明                                                    |
+| ---------- | ------------------------- | ------------------------------------------------------- |
+| `rules`    | `Record<string, AnyRule>` | `RuleMapper` によってこのノードにマッピングされたルール |
+| `rule`     | `RuleInfo<T, O>`          | 現在のルールのこのノードに対する解決済み設定            |
+
+`rule` ゲッターは、現在評価中のルール（`document.currentRule.name` 経由）の設定を `rules` レコードから取得し、`optimizeOption()` で解決します。現在評価中のルールがない場合はエラーをスローします。
+
+### `is()` による型の絞り込み
+
+`is()` メソッドは `this is NodeTypeOf<NType, T, O>` を返し、TypeScript の型の絞り込みを可能にします：
+
+```typescript
+function processNode(node: MLNode<any, any>) {
+  if (node.is(node.ELEMENT_NODE)) {
+    // node は MLElement<any, any> に絞り込まれる
+    console.log(node.localName);
+  } else if (node.is(node.TEXT_NODE)) {
+    // node は MLText<any, any> に絞り込まれる
+    console.log(node.isWhitespace());
+  } else if (node.is(node.MARKUPLINT_PREPROCESSOR_BLOCK)) {
+    // node は MLBlock<any, any> に絞り込まれる
+    console.log(node.blockBehavior?.type);
+  }
+}
+```
+
+## MLParentNode
+
+**ソース:** `src/ml-dom/node/parent-node.ts`
+
+子を持てるノード（`MLElement`、`MLDocument`、`MLDocumentFragment`）の抽象基底クラスです。DOM `ParentNode` ミックスインを実装します。
+
+### プロパティ
+
+| プロパティ          | 型                            | 説明                                 |
+| ------------------- | ----------------------------- | ------------------------------------ |
+| `children`          | `HTMLCollectionOf<MLElement>` | 要素のみの子ノード（キャッシュ済み） |
+| `childElementCount` | `number`                      | 子要素の数                           |
+| `firstElementChild` | `MLElement \| null`           | 最初の子要素                         |
+| `lastElementChild`  | `MLElement \| null`           | 最後の子要素                         |
+
+### メソッド
+
+| メソッド           | シグネチャ                                                   | 説明                                                                       |
+| ------------------ | ------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| `querySelector`    | `querySelector(selectors: string): MLElement \| null`        | CSS セレクタにマッチする最初の子孫要素                                     |
+| `querySelectorAll` | `querySelectorAll(selectors: string): NodeListOf<MLElement>` | CSS セレクタにマッチするすべての子孫要素（セレクタ文字列ごとにキャッシュ） |
+
+### `_descendantsToArray(filter?)`
+
+`syncWalk` を使ってツリーを再帰的に走査し、フィルタされた子孫の配列を返す protected メソッドです。`querySelectorAll` の内部で使用されます。