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

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

@@ -0,0 +1,269 @@
+# MLDOM における Pretender システム
+
+**主要ソース:** `src/ml-dom/node/element.ts`（`pretending()`、`matchMLSelector()`、プロパティゲッター）
+**関連:** `src/ml-dom/node/document.ts`（`_pretending()`）、`src/ml-dom/helper/accname.ts`（`getAccnameFromPretender()`）
+
+## 概要
+
+Pretender システムは、著者定義コンポーネント（例: `<MyButton>`、`<AppLink>`）をリント時に標準 HTML 要素（例: `<button>`、`<a>`）として扱えるようにします。これは HTML セマンティクスに依存するルール — `wai-aria`（アクセシブル名/ロールの検証）や `permitted-contents`（コンテンツモデルの検証）など — がフレームワークコンポーネントに対して正しく動作するために不可欠です。
+
+このシステムは、標準 HTML 要素を表す**仮想 MLElement** を作成し、元のコンポーネント要素と仮想要素の間に**双方向リンク**を確立することで機能します。MLDOM のプロパティゲッターやメソッドはこのリンクを確認し、適切な場合に透過的に pretender のデータを返します。
+
+Pretender の設定構文については、[markuplint 設定ドキュメント](https://markuplint.dev/docs/configuration/properties#pretenders)を参照してください。
+
+## アーキテクチャ
+
+### 初期化フロー
+
+Pretender の初期化は `MLDocument` のコンストラクション中に、すべてのノードが作成された後、ルールマッピングの前に行われます：
+
+```
+MLDocument コンストラクタ
+  ├── 1. AST をパース → MLDOM ノードを作成（nodeList）
+  ├── 2. _pretending(pretenders)          ← Pretender の初期化
+  │     └── nodeList の各 ELEMENT_NODE に対して:
+  │           └── element.pretending(pretenders)
+  └── 3. _ruleMapping(ruleset)            ← ルールの割り当て
+```
+
+この順序は意図的です：pretender はルールマッピングの**前に**確立される必要があります。なぜなら、ルールセレクタ（例: `button` をターゲットにした `nodeRules`）は pretender のアイデンティティに対してマッチする必要があるためです。
+
+### `pretending()` メソッド
+
+`MLElement` の `pretending()` メソッドがコアの初期化ロジックです。ドキュメントのコンストラクション中に、要素ごとに1回呼び出されます。
+
+**ステップ 1: マッチする設定を検索**
+
+```typescript
+const pretenderConfig = pretenders?.find(option => this.matches(option.selector));
+```
+
+Pretender 設定を反復し、CSS セレクタがこの要素にマッチする最初の設定を見つけます。
+
+**ステップ 2: `as` 属性によるフォールバック**
+
+```typescript
+const asAttrValue = this.getAttribute('as');
+const pretenderElement =
+  pretenderConfig?.as ??
+  (this.elementType === 'html' || !asAttrValue ? null : { element: asAttrValue, inheritAttrs: true });
+```
+
+明示的な設定がマッチしないが、要素が非 HTML 要素（つまり `elementType !== 'html'`）で `as` 属性を持つ場合、その属性値をフォールバックとして使用します。これにより、明示的な設定なしで `<MyButton as="button">` が動作します。
+
+**ステップ 3: Pretender 定義の解決**
+
+`as` フィールドは単純な文字列（タグ名）か、詳細オプションを持つ `OriginalNode` オブジェクトのいずれかです：
+
+| フィールド               | 型               | 説明                                              |
+| ------------------------ | ---------------- | ------------------------------------------------- |
+| `element`                | `string`         | ターゲットの HTML タグ名（例: `"button"`、`"a"`） |
+| `namespace`              | `string?`        | SVG 要素の場合 `'svg'`。デフォルトは `'html'`     |
+| `inheritAttrs`           | `boolean?`       | 元の要素の属性を仮想要素にコピーする              |
+| `attrs`                  | `Array?`         | 仮想要素に追加する属性                            |
+| `attrs[].value.fromAttr` | `string?`        | 元の要素の指定された属性から値を継承する          |
+| `aria`                   | `PretenderARIA?` | アクセシブル名の設定                              |
+
+**ステップ 4: 仮想要素の作成**
+
+合成 AST ノードで新しい `MLElement` が構築されます：
+
+```typescript
+const as = new MLElement<T, O>(
+  {
+    ...this._astToken,
+    uuid: this.uuid + '_pretender',
+    raw: `<${nodeName}>`,
+    nodeName,
+    namespace,
+    elementType: 'html',
+    attributes, // inheritAttrs + attrs からマージ
+  },
+  this.ownerMLDocument,
+);
+```
+
+仮想要素は元の要素の AST トークンをベースとして再利用し（ソース位置を継承）、タグ名、名前空間、属性をオーバーライドします。
+
+**ステップ 5: 双方向リンクの設定**
+
+```typescript
+as.pretenderContext = { type: 'origin', origin: this };
+this.pretenderContext = { type: 'pretender', as, aria };
+```
+
+**ステップ 6: 子ノードの共有**
+
+```typescript
+as.resetChildren(this.childNodes);
+```
+
+仮想要素は元の要素の子ノードを受け取り、コンテンツモデルの検証が同じ子に対して動作するようにします。
+
+### `pretenderContext` 型
+
+```typescript
+// 元の要素上（例: <MyButton>）
+{ type: 'pretender', as: MLElement, aria?: PretenderARIA }
+
+// 仮想要素上（例: 合成された <button>）
+{ type: 'origin', origin: MLElement }
+
+// 非参加
+null
+```
+
+## プロパティの委譲
+
+`pretenderContext.type === 'pretender'` の場合、いくつかの `MLElement` プロパティゲッターが仮想要素に委譲します：
+
+### 名前プロパティ
+
+```
+<MyButton>  (pretenderContext.type === 'pretender', as → <button>)
+
+localName  → this.pretenderContext.as.localName  → "button"
+nodeName   → this.pretenderContext.as.nodeName   → "BUTTON"
+tagName    → this.pretenderContext.as.nodeName   → "BUTTON"
+rawName    → this._astToken.nodeName             → "MyButton"（影響なし）
+```
+
+`rawName` はソースを常に反映する唯一の名前プロパティです。これにより、元のタグ名を必要とするルール（例: 命名規則ルール）が引き続きアクセスできます。
+
+### 属性アクセス
+
+| メソッド/プロパティ           | Pretender 時の動作                                                              |
+| ----------------------------- | ------------------------------------------------------------------------------- |
+| `attributes`                  | **仮想要素の**属性を返す（重複排除済み）                                        |
+| `getAttributeTokens()`        | **仮想要素の**属性トークンを返す                                                |
+| `getAttribute(name)`          | **仮想要素の**属性を検索する                                                    |
+| `hasAttribute(name)`          | **仮想要素**の `getAttribute` に委譲する                                        |
+| `getAttributePretended(name)` | Pretender コンテキストを**無視**し、**元の**要素の `#attributes` を直接検索する |
+
+`getAttributePretended()` はアクセシブル名の計算のために特別に設計されています。pretender の `aria.name` が `{ fromAttr: "label" }` を指定している場合、システムは仮想 `<button>` からではなく、元の `<MyButton label="Save">` の `label` 属性を読み取る必要があります。
+
+### ルール設定
+
+`rule` ゲッターは**逆方向**の特殊な委譲を持ちます：
+
+```typescript
+// 仮想要素上（type === 'origin'）：
+get rule() {
+  return this.pretenderContext.origin.rule;  // 元の要素に委譲
+}
+```
+
+これは、ルールが仮想要素で `element.rule` にアクセスすると、元の要素のルール設定を取得することを意味します。ルールはセレクタマッチングによってノードにマッピングされ、ルールマッピングはドキュメントの `nodeList` に存在する元の要素をターゲットにし、仮想要素はターゲットにしないためです。
+
+## セレクタマッチング
+
+### 2段階マッチング
+
+`matchMLSelector()` は pretender 要素に対して2段階戦略を実装します：
+
+```
+フェーズ 1: Pretender のアイデンティティとしてマッチ
+  セレクタ "button"  →  <button>（仮想）に対してマッチ  →  ヒット
+
+フェーズ 2: 元のアイデンティティとしてマッチ（フェーズ 1 がミスした場合のみ）
+  セレクタ "MyButton"  →  一時的に pretenderContext を null にする
+                        →  <MyButton>（元）に対してマッチ  →  ヒット
+                        →  pretenderContext を復元する
+```
+
+これにより、両方のターゲティング戦略が機能します：
+
+- **`button`** がマッチ：セマンティック要素をターゲットにしたルール（例: `<button>` の ARIA ルール）
+- **`MyButton`** がマッチ：コンポーネントをターゲットにしたルール（例: `MyButton` の `nodeRules`）
+
+### ルールマッピングへの影響
+
+`matchMLSelector()` はルールマッピングフェーズで `RuleMapper` によって使用されるため、pretender 対応のマッチングは以下を意味します：
+
+- `selector: "button"` の `nodeRules` エントリは、`<MyButton>` が `<button>` として振る舞う場合にマッチする
+- `selector: "MyButton"` の `nodeRules` エントリもマッチする。フェーズ 2 が元のアイデンティティにフォールバックするため
+
+## アクセシブル名の計算
+
+`getAccname()` ヘルパーは `getAccnameFromPretender()` を通じて pretender システムと統合されます：
+
+```
+getAccname(element)
+  ├── 1. @markuplint/ml-spec の get() を試行（標準 ARIA 計算）
+  ├── 2. getAccnameFromPretender(element) を試行   ← Pretender 固有
+  │     └── pretenderContext.type === 'pretender'
+  │         かつ pretenderContext.aria?.name が存在する場合:
+  │           ├── aria.name === true → "some-name(Pretender Options)"
+  │           └── aria.name === { fromAttr: "label" }
+  │               → el.getAttributePretended("label")
+  │               → 元の要素の属性から読み取る
+  ├── 3. aria-hidden/hidden をチェック → ""
+  ├── 4. accessibleNameFromContent をチェック → 子テキストの再帰的結合
+  └── 5. デフォルト → ""
+```
+
+重要な設計上の選択として、`getAccnameFromPretender()` は `el.getAttribute(attrName)` **ではなく** `el.getAttributePretended(attrName)` を呼び出し、pretender コンテキストをバイパスして元の要素から属性を読み取ります。これは `label` 属性が仮想 `<button>` ではなく元の `<MyButton label="Save">` に存在するためです。
+
+## `toString(fixed)` への影響
+
+`fixed=true` の場合、`MLElement.toString()` は pretender 要素に対して**生のソース**を返します：
+
+```typescript
+if (this.pretenderContext?.type === 'pretender') {
+  return this.raw;
+}
+```
+
+pretender は仮想的な構成物であるため、これは正しい動作です — pretender のアイデンティティに対して「修正」すべきソースコードはありません。元のタグ `<MyButton>` は出力で変更されずに残るべきです。
+
+## `walkOn()` への影響
+
+Pretender システムによって作成された仮想要素はドキュメントの `nodeList` に**含まれません**。元の要素（`<MyButton>`）のみが走査されます。`localName`、`nodeName`、その他のプロパティが pretender に委譲するため、ルールは走査された要素にアクセスする際に pretender のアイデンティティを確認できます。
+
+```
+document.walkOn('Element', el => {
+  // el は <MyButton> だが:
+  // el.localName === "button"    （pretender から）
+  // el.rawName === "MyButton"    （元の要素から）
+  // el.attributes は継承 + 設定された属性を含む
+});
+```
+
+## データフロー図
+
+```
+設定（pretenders 配列）
+        │
+        ▼
+MLDocument._pretending()
+        │
+        ▼（nodeList の各要素に対して）
+MLElement.pretending()
+        │
+        ├─ セレクタで一致する設定を検索
+        ├─ フォールバック: `as` 属性を持つ非 HTML 要素
+        │
+        ▼
+仮想 MLElement を作成
+        │
+        ├─ タグ名、名前空間は設定から
+        ├─ 属性: inheritAttrs + 明示的属性
+        └─ 子: 元の要素と共有
+        │
+        ▼
+双方向リンク
+        │
+        ├─ Original.pretenderContext = { type: 'pretender', as: virtual, aria }
+        └─ Virtual.pretenderContext  = { type: 'origin', origin: original }
+        │
+        ▼
+プロパティ委譲が有効化
+        │
+        ├─ localName, nodeName, tagName → 仮想要素
+        ├─ attributes, getAttributeTokens() → 仮想要素
+        ├─ rawName, fixedNodeName → 元の要素（影響なし）
+        ├─ matchMLSelector() → 2段階（仮想を先に、次に元）
+        ├─ rule（仮想要素上） → 元の要素に委譲
+        ├─ getAccname() → pretender ARIA 設定 → getAttributePretended()
+        └─ toString(fixed) → raw（修正は適用されない）
+```

package/docs/ml-dom/pretender.md

@@ -0,0 +1,269 @@
+# Pretender System in MLDOM
+
+**Primary source:** `src/ml-dom/node/element.ts` (`pretending()`, `matchMLSelector()`, property getters)
+**Related:** `src/ml-dom/node/document.ts` (`_pretending()`), `src/ml-dom/helper/accname.ts` (`getAccnameFromPretender()`)
+
+## Overview
+
+The pretender system allows authored components (e.g., `<MyButton>`, `<AppLink>`) to be treated as standard HTML elements (e.g., `<button>`, `<a>`) during linting. This is critical for rules that depend on HTML semantics — such as `wai-aria` (accessible name/role validation) and `permitted-contents` (content model validation) — to work correctly with framework components.
+
+The system works by creating a **virtual MLElement** that represents the standard HTML element, and establishing a **bidirectional link** between the original component element and the virtual element. MLDOM property getters and methods check this link to transparently return the pretender's data when appropriate.
+
+For pretender configuration syntax, see the [markuplint configuration documentation](https://markuplint.dev/docs/configuration/properties#pretenders).
+
+## Architecture
+
+### Initialization Flow
+
+Pretender initialization happens during `MLDocument` construction, after all nodes are created but before rule mapping:
+
+```
+MLDocument constructor
+  ├── 1. Parse AST → create MLDOM nodes (nodeList)
+  ├── 2. _pretending(pretenders)          ← Pretender initialization
+  │     └── For each ELEMENT_NODE in nodeList:
+  │           └── element.pretending(pretenders)
+  └── 3. _ruleMapping(ruleset)            ← Rule assignment
+```
+
+This ordering is intentional: pretenders must be established **before** rule mapping, because rule selectors (e.g., `nodeRules` targeting `button`) need to match against the pretender identity.
+
+### `pretending()` Method
+
+The `pretending()` method on `MLElement` is the core initialization logic. It is called once per element during document construction.
+
+**Step 1: Find matching config**
+
+```typescript
+const pretenderConfig = pretenders?.find(option => this.matches(option.selector));
+```
+
+Iterate through the pretender configurations and find the first one whose CSS selector matches this element.
+
+**Step 2: Fallback via `as` attribute**
+
+```typescript
+const asAttrValue = this.getAttribute('as');
+const pretenderElement =
+  pretenderConfig?.as ??
+  (this.elementType === 'html' || !asAttrValue ? null : { element: asAttrValue, inheritAttrs: true });
+```
+
+If no explicit config matches but the element is a non-HTML element (i.e., `elementType !== 'html'`) and has an `as` attribute, use that attribute value as a fallback. This allows `<MyButton as="button">` to work without explicit config.
+
+**Step 3: Resolve the pretender definition**
+
+The `as` field can be either a simple string (tag name) or an `OriginalNode` object with detailed options:
+
+| Field                    | Type             | Description                                                            |
+| ------------------------ | ---------------- | ---------------------------------------------------------------------- |
+| `element`                | `string`         | Target HTML tag name (e.g., `"button"`, `"a"`)                         |
+| `namespace`              | `string?`        | `'svg'` for SVG elements; defaults to `'html'`                         |
+| `inheritAttrs`           | `boolean?`       | Copy the original element's attributes to the virtual element          |
+| `attrs`                  | `Array?`         | Additional attributes to add to the virtual element                    |
+| `attrs[].value.fromAttr` | `string?`        | Inherit the value from the specified attribute on the original element |
+| `aria`                   | `PretenderARIA?` | Accessible name configuration                                          |
+
+**Step 4: Create the virtual element**
+
+A new `MLElement` is constructed with a synthetic AST node:
+
+```typescript
+const as = new MLElement<T, O>(
+  {
+    ...this._astToken,
+    uuid: this.uuid + '_pretender',
+    raw: `<${nodeName}>`,
+    nodeName,
+    namespace,
+    elementType: 'html',
+    attributes, // merged from inheritAttrs + attrs
+  },
+  this.ownerMLDocument,
+);
+```
+
+The virtual element reuses the original element's AST token as a base (inheriting source position), but overrides the tag name, namespace, and attributes.
+
+**Step 5: Set up bidirectional links**
+
+```typescript
+as.pretenderContext = { type: 'origin', origin: this };
+this.pretenderContext = { type: 'pretender', as, aria };
+```
+
+**Step 6: Share children**
+
+```typescript
+as.resetChildren(this.childNodes);
+```
+
+The virtual element receives the original element's child nodes, so that content model validation works against the same children.
+
+### `pretenderContext` Type
+
+```typescript
+// On the original element (e.g., <MyButton>)
+{ type: 'pretender', as: MLElement, aria?: PretenderARIA }
+
+// On the virtual element (e.g., the synthetic <button>)
+{ type: 'origin', origin: MLElement }
+
+// Not participating
+null
+```
+
+## Property Delegation
+
+When `pretenderContext.type === 'pretender'`, several `MLElement` property getters delegate to the virtual element:
+
+### Name Properties
+
+```
+<MyButton>  (pretenderContext.type === 'pretender', as → <button>)
+
+localName  → this.pretenderContext.as.localName  → "button"
+nodeName   → this.pretenderContext.as.nodeName   → "BUTTON"
+tagName    → this.pretenderContext.as.nodeName   → "BUTTON"
+rawName    → this._astToken.nodeName             → "MyButton"  (unaffected)
+```
+
+`rawName` is the only name property that always reflects the source. This allows rules that care about the original tag name (e.g., naming convention rules) to still access it.
+
+### Attribute Access
+
+| Method/Property               | Pretender behavior                                                                        |
+| ----------------------------- | ----------------------------------------------------------------------------------------- |
+| `attributes`                  | Returns the **virtual element's** attributes (deduplicated)                               |
+| `getAttributeTokens()`        | Returns the **virtual element's** attribute tokens                                        |
+| `getAttribute(name)`          | Searches the **virtual element's** attributes                                             |
+| `hasAttribute(name)`          | Delegates to `getAttribute` on the **virtual element**                                    |
+| `getAttributePretended(name)` | **Ignores** pretender context; searches the **original** element's `#attributes` directly |
+
+`getAttributePretended()` is specifically designed for the accessible name computation: when a pretender's `aria.name` specifies `{ fromAttr: "label" }`, the system needs to read the `label` attribute from the original `<MyButton label="Save">`, not from the virtual `<button>`.
+
+### Rule Configuration
+
+The `rule` getter has special delegation in the **opposite direction**:
+
+```typescript
+// On the virtual element (type === 'origin'):
+get rule() {
+  return this.pretenderContext.origin.rule;  // Delegate to the original
+}
+```
+
+This means when a rule accesses `element.rule` on the virtual element, it gets the rule configuration from the original element. This is because rules are mapped to nodes by selector matching, and the rule mapping targets the original elements (which exist in the document's `nodeList`), not the virtual elements.
+
+## Selector Matching
+
+### Two-Phase Matching
+
+`matchMLSelector()` implements a two-phase strategy for pretender elements:
+
+```
+Phase 1: Match as the pretender identity
+  selector "button"  →  match against <button> (virtual)  →  HIT
+
+Phase 2: Match as the original identity (only if Phase 1 missed)
+  selector "MyButton"  →  temporarily null out pretenderContext
+                        →  match against <MyButton> (original)  →  HIT
+                        →  restore pretenderContext
+```
+
+This ensures both targeting strategies work:
+
+- **`button`** matches: rules that target the semantic element (e.g., ARIA rules for `<button>`)
+- **`MyButton`** matches: rules that target the component (e.g., `nodeRules` for `MyButton`)
+
+### Impact on Rule Mapping
+
+Since `matchMLSelector()` is used by `RuleMapper` during the rule mapping phase, pretender-aware matching means:
+
+- A `nodeRules` entry with `selector: "button"` will match `<MyButton>` if it pretends to be `<button>`
+- A `nodeRules` entry with `selector: "MyButton"` will also match, because Phase 2 falls back to the original identity
+
+## Accessible Name Computation
+
+The `getAccname()` helper integrates with the pretender system via `getAccnameFromPretender()`:
+
+```
+getAccname(element)
+  ├── 1. Try @markuplint/ml-spec get() (standard ARIA computation)
+  ├── 2. Try getAccnameFromPretender(element)       ← Pretender-specific
+  │     └── If pretenderContext.type === 'pretender'
+  │         and pretenderContext.aria?.name exists:
+  │           ├── aria.name === true → "some-name(Pretender Options)"
+  │           └── aria.name === { fromAttr: "label" }
+  │               → el.getAttributePretended("label")
+  │               → reads from the ORIGINAL element's attributes
+  ├── 3. Check aria-hidden/hidden → ""
+  ├── 4. Check accessibleNameFromContent → recursive child text
+  └── 5. Default → ""
+```
+
+The key design choice is that `getAccnameFromPretender()` calls `el.getAttributePretended(attrName)` — **not** `el.getAttribute(attrName)` — to read the attribute from the original element, bypassing the pretender context. This is because the `label` attribute exists on `<MyButton label="Save">`, not on the virtual `<button>`.
+
+## Effect on `toString(fixed)`
+
+When `fixed=true`, `MLElement.toString()` returns the **raw source** for pretender elements:
+
+```typescript
+if (this.pretenderContext?.type === 'pretender') {
+  return this.raw;
+}
+```
+
+This is correct because the pretender is a virtual construct — there is no source code to "fix" for the pretender identity. The original tag `<MyButton>` should remain unchanged in the output.
+
+## Effect on `walkOn()`
+
+Virtual elements created by the pretender system are **not** in the document's `nodeList`. Only the original elements (`<MyButton>`) are walked. Since `localName`, `nodeName`, and other properties delegate to the pretender, rules see the pretender identity when accessing the walked element.
+
+```
+document.walkOn('Element', el => {
+  // el is <MyButton>, but:
+  // el.localName === "button"    (from pretender)
+  // el.rawName === "MyButton"    (from original)
+  // el.attributes includes inherited + configured attrs
+});
+```
+
+## Data Flow Diagram
+
+```
+Configuration (pretenders array)
+        │
+        ▼
+MLDocument._pretending()
+        │
+        ▼ (for each element in nodeList)
+MLElement.pretending()
+        │
+        ├─ Find matching config by selector
+        ├─ Fallback: non-HTML element with `as` attribute
+        │
+        ▼
+Create virtual MLElement
+        │
+        ├─ Tag name, namespace from config
+        ├─ Attributes: inheritAttrs + explicit attrs
+        └─ Children: shared with original
+        │
+        ▼
+Bidirectional link
+        │
+        ├─ Original.pretenderContext = { type: 'pretender', as: virtual, aria }
+        └─ Virtual.pretenderContext  = { type: 'origin', origin: original }
+        │
+        ▼
+Property delegation active
+        │
+        ├─ localName, nodeName, tagName → virtual
+        ├─ attributes, getAttributeTokens() → virtual
+        ├─ rawName, fixedNodeName → original (unaffected)
+        ├─ matchMLSelector() → two-phase (virtual first, then original)
+        ├─ rule (on virtual) → delegates to original
+        ├─ getAccname() → pretender ARIA config → getAttributePretended()
+        └─ toString(fixed) → raw (no fix applied)
+```