@markuplint/ml-spec 4.10.2 → 5.0.0-alpha.0

package/docs/spec-resolution.ja.md

@@ -107,7 +107,7 @@ gAttrs['#HTMLGlobalAttrs'] = {
 #### 3. ARIA定義
 
 各ARIAバージョン（`1.1`, `1.2`, `1.3`）について、`roles`, `props`,
-`graphicsRoles` の3つの配列が `mergeArray` を使ってマージされます：
+`graphicsRoles`, `dpubRoles` の4つの配列が `mergeArray` を使ってマージされます：
 
 ```ts
 def['#aria'] = {
@@ -115,6 +115,7 @@ def['#aria'] = {
     roles: mergeArray(def['#aria']['1.1'].roles, extendedSpec.def['#aria']['1.1'].roles),
     props: mergeArray(def['#aria']['1.1'].props, extendedSpec.def['#aria']['1.1'].props),
     graphicsRoles: mergeArray(def['#aria']['1.1'].graphicsRoles, extendedSpec.def['#aria']['1.1'].graphicsRoles),
+    dpubRoles: mergeArray(def['#aria']['1.1'].dpubRoles, extendedSpec.def['#aria']['1.1'].dpubRoles),
   },
   // 1.2 と 1.3 も同様
 };
@@ -142,7 +143,35 @@ for (const modelName of keys) {
 （例: `#phrasing` に `<router-link>` を追加）、
 まったく新しいカテゴリを定義したりできます。
 
-#### 5. 要素仕様
+#### 5. ディレクティブパターン
+
+拡張仕様が `directivePatterns` を提供する場合、既存の配列に連結されます：
+
+```ts
+result.directivePatterns = [...(result.directivePatterns ?? []), ...extendedSpec.directivePatterns];
+```
+
+単純な配列結合です。コアエンジンはパターンを順番に評価します
+（最初のマッチが優先）。そのため、フレームワーク spec はパターンを
+最も具体的なものから最も一般的なものの順で定義する必要があります。
+
+#### 6. `useIDLAttributeNames`
+
+拡張仕様が `useIDLAttributeNames` を明示的に設定している場合（`true` または
+`false`）、現在の値を上書きします：
+
+```ts
+if (extendedSpec.useIDLAttributeNames != null) {
+  result.useIDLAttributeNames = extendedSpec.useIDLAttributeNames;
+}
+```
+
+これは明示的な `null` ガード付きの last-write-wins セマンティクスです。
+プロパティを省略しても以前に設定された値はリセットされません。
+このフラグは `@markuplint/ml-core` の `MLAttr` コンストラクタで使用され、
+IDL-コンテンツ属性名解決（例: `className` → `class`）を有効化します。
+
+#### 7. 要素仕様
 
 要素は名前で照合されます（大文字小文字を区別しない比較）。
 ベース仕様の各要素について：
@@ -479,7 +508,7 @@ function getName(def: NamedDefinition): string {
 | --- | --------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------- | ------------------------------------------------- |
 | 1   | `getSpecByTagName`                            | `Map<string, any>`                                                | 名前空間修飾名（例: `"svg:circle"`）            | `ElementSpec \| null`                          | モジュールライフタイム（クリアなし）              |
 | 2   | `getVersionResolvedARIA`（`get-aria.ts` 内）  | `Map<string, ARIA \| null>`                                       | `localName + namespace + version`（文字列連結） | バージョン解決済みARIA仕様またはnull           | モジュールライフタイム（クリアなし）              |
-| 3   | `getContentModel`                             | `Map<Specs, Map<Element, ...>>`                                   | 外側: specs配列参照; 内側: DOM Element参照      | `PermittedContentPattern[] \| boolean \| null` | specs参照ごとに外側マップエントリを作成           |
+| 3   | `getContentModel`                             | `WeakMap<Element, ...>`                                           | DOM Element参照                                 | `PermittedContentPattern[] \| boolean \| null` | ElementがGCされるとエントリも自動削除             |
 | 4   | `contentModelCategoryToTagNames`              | `Map<Category, ReadonlyArray<string>>`                            | カテゴリ文字列（例: `"#flow"`）                 | フリーズされたソート済みタグ名配列             | モジュールライフタイム（クリアなし）              |
 | 5   | `resolveNamespace`                            | `Map<string, NamespacedElementName>`                              | `name + namespaceURI`（文字列連結）             | 解決済み名前空間オブジェクト                   | モジュールライフタイム（クリアなし）              |
 | 6   | `getAttrSpecs`（`get-attr-specs-spec.ts` 内） | `Map<string, readonly Attribute[] \| null>` + `WeakSet<MLMLSpec>` | 名前空間修飾名                                  | ソート済み属性配列またはnull                   | スキーマ参照変更時にクリア（WeakSetチェック経由） |
@@ -504,12 +533,11 @@ if (!schemaCache.has(schema)) {
 }
 ```
 
-**ネストされたキャッシュ:** `getContentModel` キャッシュ（項目3）は
-2段階の `Map<Specs, Map<Element, ...>>` 構造を使用します。
-外側のマップはspecs配列参照でキーが付けられるため、
-異なる仕様設定は別々のキャッシュを維持します。
-内側のマップはDOM Element参照でキーが付けられるため、
-同じ仕様コンテキスト内で同じ要素を再クエリするとO(1)になります。
+**WeakMapキャッシュ:** `getContentModel` キャッシュ（項目3）は
+`WeakMap<Element, ...>` を使用し、DOM Element参照をキーとします。
+同じ要素を再クエリするとO(1)になります。
+要素がガベージコレクションされると（例: 再パース後）、
+キャッシュエントリも自動的に削除され、メモリリークを防止します。
 
 **決定論的キー:** 項目1、2、5のキャッシュは文字列連結をキーに使用します。
 `resolveNamespace` は同じ入力に対して決定論的な出力を生成し、

package/docs/spec-resolution.md

@@ -111,8 +111,8 @@ the extension.
 
 #### 3. ARIA Definitions
 
-For each ARIA version (`1.1`, `1.2`, `1.3`), the three arrays -- `roles`,
-`props`, and `graphicsRoles` -- are merged using `mergeArray`:
+For each ARIA version (`1.1`, `1.2`, `1.3`), the four arrays -- `roles`,
+`props`, `graphicsRoles`, and `dpubRoles` -- are merged using `mergeArray`:
 
 ```ts
 def['#aria'] = {
@@ -120,6 +120,7 @@ def['#aria'] = {
     roles: mergeArray(def['#aria']['1.1'].roles, extendedSpec.def['#aria']['1.1'].roles),
     props: mergeArray(def['#aria']['1.1'].props, extendedSpec.def['#aria']['1.1'].props),
     graphicsRoles: mergeArray(def['#aria']['1.1'].graphicsRoles, extendedSpec.def['#aria']['1.1'].graphicsRoles),
+    dpubRoles: mergeArray(def['#aria']['1.1'].dpubRoles, extendedSpec.def['#aria']['1.1'].dpubRoles),
   },
   // same for 1.2 and 1.3
 };
@@ -146,7 +147,36 @@ This means a framework can add its custom elements to existing categories
 (e.g., adding `<router-link>` to `#phrasing`) or define entirely new
 categories.
 
-#### 5. Element Specs
+#### 5. Directive Patterns
+
+If the extended spec provides `directivePatterns`, they are concatenated onto the
+existing array:
+
+```ts
+result.directivePatterns = [...(result.directivePatterns ?? []), ...extendedSpec.directivePatterns];
+```
+
+This is simple array concatenation. The core engine evaluates patterns in order
+(first match wins), so framework specs should define their patterns from most
+specific to most general.
+
+#### 6. `useIDLAttributeNames`
+
+If the extended spec explicitly sets `useIDLAttributeNames` (to `true` or
+`false`), it overrides the current value:
+
+```ts
+if (extendedSpec.useIDLAttributeNames != null) {
+  result.useIDLAttributeNames = extendedSpec.useIDLAttributeNames;
+}
+```
+
+This is a last-write-wins semantic with explicit `null` guard -- omitting the
+property does not reset a previously set value. This flag is consumed by
+`@markuplint/ml-core`'s `MLAttr` constructor to enable IDL-to-content attribute
+name resolution (e.g., `className` -> `class`).
+
+#### 7. Element Specs
 
 Elements are matched by name (case-insensitive comparison). For each element in
 the base spec:
@@ -486,14 +516,14 @@ caches provide significant performance benefits.
 
 ### Cache Inventory
 
-| #   | Location                                        | Cache Type                                                        | Key                                                        | Value                                          | Invalidation                                              |
-| --- | ----------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------- |
-| 1   | `getSpecByTagName`                              | `Map<string, any>`                                                | Namespace-qualified name (e.g., `"svg:circle"`)            | `ElementSpec \| null`                          | Module lifetime (never cleared)                           |
-| 2   | `getVersionResolvedARIA` (inside `get-aria.ts`) | `Map<string, ARIA \| null>`                                       | `localName + namespace + version` (string concatenation)   | Version-resolved ARIA spec or null             | Module lifetime (never cleared)                           |
-| 3   | `getContentModel`                               | `Map<Specs, Map<Element, ...>>`                                   | Outer: specs array reference; Inner: DOM Element reference | `PermittedContentPattern[] \| boolean \| null` | Outer map entry created per unique specs reference        |
-| 4   | `contentModelCategoryToTagNames`                | `Map<Category, ReadonlyArray<string>>`                            | Category string (e.g., `"#flow"`)                          | Frozen sorted array of tag names               | Module lifetime (never cleared)                           |
-| 5   | `resolveNamespace`                              | `Map<string, NamespacedElementName>`                              | `name + namespaceURI` (string concatenation)               | Resolved namespace object                      | Module lifetime (never cleared)                           |
-| 6   | `getAttrSpecs` (in `get-attr-specs-spec.ts`)    | `Map<string, readonly Attribute[] \| null>` + `WeakSet<MLMLSpec>` | Namespace-qualified name                                   | Sorted attribute array or null                 | Cleared when schema reference changes (via WeakSet check) |
+| #   | Location                                        | Cache Type                                                        | Key                                                      | Value                                          | Invalidation                                              |
+| --- | ----------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------- |
+| 1   | `getSpecByTagName`                              | `Map<string, any>`                                                | Namespace-qualified name (e.g., `"svg:circle"`)          | `ElementSpec \| null`                          | Module lifetime (never cleared)                           |
+| 2   | `getVersionResolvedARIA` (inside `get-aria.ts`) | `Map<string, ARIA \| null>`                                       | `localName + namespace + version` (string concatenation) | Version-resolved ARIA spec or null             | Module lifetime (never cleared)                           |
+| 3   | `getContentModel`                               | `WeakMap<Element, ...>`                                           | DOM Element reference                                    | `PermittedContentPattern[] \| boolean \| null` | Entries automatically removed when Element is GC'd        |
+| 4   | `contentModelCategoryToTagNames`                | `Map<Category, ReadonlyArray<string>>`                            | Category string (e.g., `"#flow"`)                        | Frozen sorted array of tag names               | Module lifetime (never cleared)                           |
+| 5   | `resolveNamespace`                              | `Map<string, NamespacedElementName>`                              | `name + namespaceURI` (string concatenation)             | Resolved namespace object                      | Module lifetime (never cleared)                           |
+| 6   | `getAttrSpecs` (in `get-attr-specs-spec.ts`)    | `Map<string, readonly Attribute[] \| null>` + `WeakSet<MLMLSpec>` | Namespace-qualified name                                 | Sorted attribute array or null                 | Cleared when schema reference changes (via WeakSet check) |
 
 ### Cache Characteristics
 
@@ -516,11 +546,10 @@ if (!schemaCache.has(schema)) {
 }
 ```
 
-**Nested caching:** The `getContentModel` cache (item 3) uses a two-level
-`Map<Specs, Map<Element, ...>>` structure. The outer map is keyed by the specs
-array reference, so different spec configurations maintain separate caches. The
-inner map is keyed by DOM Element reference, so re-querying the same element
-within the same spec context is O(1).
+**WeakMap caching:** The `getContentModel` cache (item 3) uses a
+`WeakMap<Element, ...>` keyed by DOM Element reference. Re-querying the same
+element is O(1). When elements are garbage-collected (e.g., after a re-parse),
+their cache entries are automatically removed, preventing memory leaks.
 
 **Deterministic keys:** Caches in items 1, 2, and 5 use string concatenation
 for keys. Since `resolveNamespace` produces deterministic output for the same

package/docs/type-definitions.ja.md

@@ -69,7 +69,7 @@ type SpecDefs = {
 ```
 
 - **`#globalAttrs`** -- カテゴリをキーとした属性定義。各カテゴリ（例: `#HTMLGlobalAttrs`、`#ARIAAttrs`）は部分的な属性定義のレコードにマッピングされます。
-- **`#aria`** -- 各仕様バージョン（1.1、1.2、1.3）の ARIA ロール/プロパティ定義。各バージョンには `roles`、`graphicsRoles`、`props` 配列が含まれます。
+- **`#aria`** -- 各仕様バージョン（1.1、1.2、1.3）の ARIA ロール/プロパティ定義。各バージョンには `roles`、`graphicsRoles`、`dpubRoles`、`props` 配列が含まれます。
 - **`#contentModels`** -- コンテンツモデルカテゴリからセレクタ配列へのマッピング。`Category` 値（`#flow`、`#phrasing` など）を、そのカテゴリに属する要素にマッチする CSS セレクタの配列にマッピングします。
 
 ### `ElementSpec`
@@ -137,9 +137,13 @@ type ARIARole = {
   readonly isAbstract: boolean; // 抽象ロールかどうか
   readonly deprecated: boolean; // 非推奨のロールかどうか
 
-  // コンテキスト要件
-  readonly requiredContextRole: readonly string[]; // 必要な親ロール
-  readonly requiredOwnedElements: readonly string[]; // 必要な子ロール
+  // コンテキスト要件（ARIA 1.3 名）
+  readonly requiredAccessibilityParentRole: readonly string[];
+  readonly allowedAccessibilityChildRoles: readonly string[];
+
+  // 後方互換性（ARIA 1.2 名、非推奨）
+  readonly requiredContextRole: readonly string[]; // @deprecated
+  readonly requiredOwnedElements: readonly string[]; // @deprecated
 
   // アクセシブル名の制約
   readonly accessibleNameRequired: boolean; // アクセシブル名が必須

package/docs/type-definitions.md

@@ -69,7 +69,7 @@ type SpecDefs = {
 ```
 
 - **`#globalAttrs`** -- Category-keyed attribute definitions. Each category (e.g., `#HTMLGlobalAttrs`, `#ARIAAttrs`) maps to a record of partial attribute definitions.
-- **`#aria`** -- ARIA role/property definitions for each specification version (1.1, 1.2, 1.3). Each version contains `roles`, `graphicsRoles`, and `props` arrays.
+- **`#aria`** -- ARIA role/property definitions for each specification version (1.1, 1.2, 1.3). Each version contains `roles`, `graphicsRoles`, `dpubRoles`, and `props` arrays.
 - **`#contentModels`** -- Content model category to selector array mappings. Maps `Category` values (like `#flow`, `#phrasing`) to arrays of CSS selectors that match elements belonging to that category.
 
 ### `ElementSpec`
@@ -137,9 +137,13 @@ type ARIARole = {
   readonly isAbstract: boolean; // Whether this is an abstract role
   readonly deprecated: boolean; // Whether this role is deprecated
 
-  // Context requirements
-  readonly requiredContextRole: readonly string[]; // Required parent roles
-  readonly requiredOwnedElements: readonly string[]; // Required child roles
+  // Context requirements (ARIA 1.3 names)
+  readonly requiredAccessibilityParentRole: readonly string[];
+  readonly allowedAccessibilityChildRoles: readonly string[];
+
+  // Backward compatibility (ARIA 1.2 names, deprecated)
+  readonly requiredContextRole: readonly string[]; // @deprecated
+  readonly requiredOwnedElements: readonly string[]; // @deprecated
 
   // Accessible name constraints
   readonly accessibleNameRequired: boolean; // Must have an accessible name

package/lib/algorithm/aria/accname/__tests__/test-helpers.d.ts

@@ -0,0 +1,45 @@
+import type { AccnameElement, AccnameNode, AccnameResolver } from '../types.js';
+interface ElementOptions {
+    readonly attrs?: Record<string, string>;
+    readonly children?: readonly (AccnameElement | AccnameNode)[];
+    readonly parentElement?: AccnameElement | null;
+    readonly namespaceURI?: string | null;
+}
+/**
+ * Creates a test AccnameElement (plain object).
+ *
+ * **Note:** `textContent` is computed eagerly at creation time from the initial
+ * `children`. Adding children after creation will NOT update `textContent`.
+ * Build the full child tree before calling this function.
+ *
+ * @param localName - The local tag name of the element
+ * @param options - Configuration for attributes, children, parent, and namespace
+ * @returns A plain object implementing the AccnameElement interface
+ */
+export declare function element(localName: string, options?: ElementOptions): AccnameElement;
+/**
+ * Creates a test text node.
+ *
+ * @param text - The text content of the node
+ * @returns A plain object implementing the AccnameNode interface
+ */
+export declare function textNode(text: string): AccnameNode;
+interface ResolverOptions {
+    readonly elements?: Map<string, AccnameElement>;
+    readonly labels?: Map<string, readonly AccnameElement[]>;
+    readonly nameFromContent?: Set<string>;
+    readonly hiddenIds?: Set<string>;
+    readonly allowsNameFromContentFn?: (el: AccnameElement) => boolean;
+    readonly isHiddenFn?: (el: AccnameElement) => boolean;
+    readonly embeddedControlRoles?: Set<string>;
+    readonly isEmbeddedControlFn?: (el: AccnameElement) => boolean;
+    readonly getPrecomputedNameFn?: (el: AccnameElement) => string | null;
+}
+/**
+ * Creates a test AccnameResolver.
+ *
+ * @param options - Configuration for element lookups, label associations, and behavior overrides
+ * @returns A resolver implementing the AccnameResolver interface for testing
+ */
+export declare function createTestResolver(options?: ResolverOptions): AccnameResolver;
+export {};

package/lib/algorithm/aria/accname/__tests__/test-helpers.js

@@ -0,0 +1,120 @@
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- AccnameElement wraps mutable DOM types */
+import { ELEMENT_NODE, TEXT_NODE, XHTML_NAMESPACE, EMBEDDED_CONTROL_ROLES, isNativeEmbeddedControl, } from '../../../../const/index.js';
+/**
+ * Creates a test AccnameElement (plain object).
+ *
+ * **Note:** `textContent` is computed eagerly at creation time from the initial
+ * `children`. Adding children after creation will NOT update `textContent`.
+ * Build the full child tree before calling this function.
+ *
+ * @param localName - The local tag name of the element
+ * @param options - Configuration for attributes, children, parent, and namespace
+ * @returns A plain object implementing the AccnameElement interface
+ */
+export function element(localName, options = {}) {
+    const attrs = options.attrs ?? {};
+    const childNodes = options.children ?? [];
+    const elementChildren = [];
+    for (const child of childNodes) {
+        if (child.nodeType === ELEMENT_NODE) {
+            elementChildren.push(child);
+        }
+    }
+    const el = {
+        nodeType: ELEMENT_NODE,
+        localName,
+        id: attrs['id'] ?? '',
+        namespaceURI: options.namespaceURI ?? XHTML_NAMESPACE,
+        textContent: computeTextContent(childNodes),
+        parentElement: options.parentElement ?? null,
+        children: elementChildren,
+        childNodes,
+        getAttribute(name) {
+            return attrs[name] ?? null;
+        },
+        hasAttribute(name) {
+            return name in attrs;
+        },
+    };
+    return el;
+}
+/**
+ * Creates a test text node.
+ *
+ * @param text - The text content of the node
+ * @returns A plain object implementing the AccnameNode interface
+ */
+export function textNode(text) {
+    return {
+        nodeType: TEXT_NODE,
+        textContent: text,
+    };
+}
+function computeTextContent(childNodes) {
+    return childNodes
+        .map(child => {
+        if (child.nodeType === TEXT_NODE) {
+            return child.textContent ?? '';
+        }
+        if (child.nodeType === ELEMENT_NODE) {
+            return child.textContent ?? '';
+        }
+        return '';
+    })
+        .join('');
+}
+/**
+ * Creates a test AccnameResolver.
+ *
+ * @param options - Configuration for element lookups, label associations, and behavior overrides
+ * @returns A resolver implementing the AccnameResolver interface for testing
+ */
+export function createTestResolver(options = {}) {
+    const elements = options.elements ?? new Map();
+    const labels = options.labels ?? new Map();
+    const nameFromContent = options.nameFromContent ?? new Set();
+    const hiddenIds = options.hiddenIds ?? new Set();
+    const embeddedControlRoles = options.embeddedControlRoles ?? EMBEDDED_CONTROL_ROLES;
+    return {
+        getElementById(id) {
+            return elements.get(id) ?? null;
+        },
+        getLabelsForId(id) {
+            return labels.get(id) ?? [];
+        },
+        allowsNameFromContent(el) {
+            if (options.allowsNameFromContentFn) {
+                return options.allowsNameFromContentFn(el);
+            }
+            return nameFromContent.has(el.localName);
+        },
+        isHidden(el) {
+            if (options.isHiddenFn) {
+                return options.isHiddenFn(el);
+            }
+            if (hiddenIds.has(el.id)) {
+                return true;
+            }
+            if (el.getAttribute('aria-hidden') === 'true') {
+                return true;
+            }
+            if (el.hasAttribute('hidden')) {
+                return true;
+            }
+            return false;
+        },
+        isEmbeddedControl(el) {
+            if (options.isEmbeddedControlFn) {
+                return options.isEmbeddedControlFn(el);
+            }
+            // Check explicit role
+            const role = el.getAttribute('role')?.trim().split(/\s+/)[0];
+            if (role && embeddedControlRoles.has(role)) {
+                return true;
+            }
+            // Check native HTML elements
+            return isNativeEmbeddedControl(el);
+        },
+        ...(options.getPrecomputedNameFn ? { getPrecomputedName: options.getPrecomputedNameFn } : {}),
+    };
+}

package/lib/algorithm/aria/accname/aria-steps.d.ts

@@ -0,0 +1,51 @@
+import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js';
+/**
+ * Resolves accessible name via `aria-labelledby` attribute.
+ *
+ * Implements AccName 1.2 §4.3.2 Step 2B:
+ * "If the current node has an `aria-labelledby` attribute that contains
+ * at least one valid IDREF, and the current node is not already part of
+ * an ongoing `aria-labelledby` traversal, process its IDREFs [...]"
+ *
+ * Control flow:
+ * 1. Read `aria-labelledby` attribute; return null if absent or empty.
+ * 2. Split the attribute value by whitespace into IDREF tokens.
+ * 3. Mark the current element's ID as visited (cycle prevention for A→B→A).
+ * 4. For each IDREF:
+ *    a. Skip if already visited — **except** self-references (see below).
+ *    b. Resolve the referenced element via `resolver.getElementById`.
+ *    c. Recursively compute the referenced element's name with
+ *       `inLabelledbyTraversal=true` (prevents Step 2B re-entry in `compute.ts`).
+ *    d. Each IDREF branch gets its own copy of the visited set so that
+ *       one branch's traversal does not block later branches.
+ * 5. Join all resolved parts with a space separator and flatten whitespace.
+ *
+ * **Self-reference handling** (spec-defined, not a custom extension):
+ * An element may reference its own ID in `aria-labelledby` to include its
+ * own content alongside other referenced elements. This is explicitly
+ * permitted by the spec (AccName 1.2 §4.3.2 Example 2):
+ *   `<h2 id="h" aria-labelledby="h foo">Meeting</h2>`
+ * Infinite recursion is prevented by `inLabelledbyTraversal`, not by the
+ * visited set — `computeFn` is called with `inLabelledbyTraversal=true`,
+ * which causes `compute.ts` to skip Step 2B on the referenced element.
+ *
+ * @param el - The element with a potential aria-labelledby attribute
+ * @param resolver - Environment-dependent resolver for element lookups
+ * @param visited - Set of element IDs already visited (cycle prevention)
+ * @param computeFn - The recursive accessible name computation function
+ * @returns The resolved name result, or null if aria-labelledby is not present or yields no name
+ * @see https://www.w3.org/TR/accname-1.2/#comp_labelledby_traversal — AccName 1.2 §4.3.2 Step 2B
+ */
+export declare function resolveAriaLabelledby(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: (el: AccnameElement, resolver: AccnameResolver, inLabelledbyTraversal: boolean, visited: ReadonlySet<string>) => AccnameResult): AccnameResult | null;
+/**
+ * Resolves accessible name via `aria-label` attribute.
+ *
+ * Implements AccName 1.2 §4.3.2 Step 2D:
+ * "If the current node has an `aria-label` attribute whose value is
+ * not undefined, not the empty string, and not a string of whitespace [...]"
+ *
+ * @param el - The element with a potential aria-label attribute
+ * @returns The resolved name result, or null if aria-label is not present or empty
+ * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2 Step 2D
+ */
+export declare function resolveAriaLabel(el: AccnameElement): AccnameResult | null;

package/lib/algorithm/aria/accname/aria-steps.js

@@ -0,0 +1,104 @@
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- AccnameElement wraps mutable DOM types */
+import { flattenText, makeResult } from './helpers.js';
+/**
+ * Resolves accessible name via `aria-labelledby` attribute.
+ *
+ * Implements AccName 1.2 §4.3.2 Step 2B:
+ * "If the current node has an `aria-labelledby` attribute that contains
+ * at least one valid IDREF, and the current node is not already part of
+ * an ongoing `aria-labelledby` traversal, process its IDREFs [...]"
+ *
+ * Control flow:
+ * 1. Read `aria-labelledby` attribute; return null if absent or empty.
+ * 2. Split the attribute value by whitespace into IDREF tokens.
+ * 3. Mark the current element's ID as visited (cycle prevention for A→B→A).
+ * 4. For each IDREF:
+ *    a. Skip if already visited — **except** self-references (see below).
+ *    b. Resolve the referenced element via `resolver.getElementById`.
+ *    c. Recursively compute the referenced element's name with
+ *       `inLabelledbyTraversal=true` (prevents Step 2B re-entry in `compute.ts`).
+ *    d. Each IDREF branch gets its own copy of the visited set so that
+ *       one branch's traversal does not block later branches.
+ * 5. Join all resolved parts with a space separator and flatten whitespace.
+ *
+ * **Self-reference handling** (spec-defined, not a custom extension):
+ * An element may reference its own ID in `aria-labelledby` to include its
+ * own content alongside other referenced elements. This is explicitly
+ * permitted by the spec (AccName 1.2 §4.3.2 Example 2):
+ *   `<h2 id="h" aria-labelledby="h foo">Meeting</h2>`
+ * Infinite recursion is prevented by `inLabelledbyTraversal`, not by the
+ * visited set — `computeFn` is called with `inLabelledbyTraversal=true`,
+ * which causes `compute.ts` to skip Step 2B on the referenced element.
+ *
+ * @param el - The element with a potential aria-labelledby attribute
+ * @param resolver - Environment-dependent resolver for element lookups
+ * @param visited - Set of element IDs already visited (cycle prevention)
+ * @param computeFn - The recursive accessible name computation function
+ * @returns The resolved name result, or null if aria-labelledby is not present or yields no name
+ * @see https://www.w3.org/TR/accname-1.2/#comp_labelledby_traversal — AccName 1.2 §4.3.2 Step 2B
+ */
+export function resolveAriaLabelledby(el, resolver, visited, computeFn) {
+    const labelledbyAttr = el.getAttribute('aria-labelledby');
+    if (!labelledbyAttr?.trim()) {
+        return null;
+    }
+    const ids = labelledbyAttr.trim().split(/\s+/);
+    const parts = [];
+    const newVisited = new Set(visited);
+    // Mark the current element as visited to prevent other elements from
+    // circling back to it (e.g., A → B → A).
+    if (el.id) {
+        newVisited.add(el.id);
+    }
+    for (const id of ids) {
+        // Skip IDs already visited — but allow self-references (id === el.id).
+        // The spec requires that an element CAN reference itself in
+        // aria-labelledby to include its own content alongside other IDs.
+        // Example (AccName 1.2 §4.3.2 Example 2):
+        //   <h2 id="h" aria-labelledby="h foo">Meeting</h2>
+        // Here "h" references itself, contributing "Meeting" to the result.
+        //
+        // Infinite recursion is prevented not by the visited set, but by
+        // inLabelledbyTraversal: computeFn is called with true below,
+        // which causes compute.ts to skip Step 2B (aria-labelledby) on
+        // the referenced element, so it never re-enters this function.
+        if (newVisited.has(id) && id !== el.id) {
+            continue;
+        }
+        const referenced = resolver.getElementById(id);
+        if (!referenced) {
+            continue;
+        }
+        // Each branch gets its own visited set so that one IDREF's
+        // traversal doesn't block resolution of a later IDREF.
+        const innerVisited = new Set(newVisited);
+        innerVisited.add(id);
+        const result = computeFn(referenced, resolver, true, innerVisited);
+        if (result.name) {
+            parts.push(result.name);
+        }
+    }
+    const name = flattenText(parts.join(' '));
+    if (name) {
+        return makeResult(name, 'aria-labelledby');
+    }
+    return null;
+}
+/**
+ * Resolves accessible name via `aria-label` attribute.
+ *
+ * Implements AccName 1.2 §4.3.2 Step 2D:
+ * "If the current node has an `aria-label` attribute whose value is
+ * not undefined, not the empty string, and not a string of whitespace [...]"
+ *
+ * @param el - The element with a potential aria-label attribute
+ * @returns The resolved name result, or null if aria-label is not present or empty
+ * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2 Step 2D
+ */
+export function resolveAriaLabel(el) {
+    const label = el.getAttribute('aria-label');
+    if (label?.trim()) {
+        return makeResult(label, 'aria-label');
+    }
+    return null;
+}

package/lib/algorithm/aria/accname/compute.d.ts

@@ -0,0 +1,51 @@
+import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js';
+/**
+ * Computes the accessible name for an element.
+ *
+ * Implements the Accessible Name and Description Computation algorithm
+ * per AccName 1.2 §4.3.2 ("Computation Steps") and HTML-AAM §4.1
+ * ("Accessible Name and Description Computation").
+ *
+ * Control flow (Steps map to AccName 1.2 §4.3.2):
+ *
+ * 1. **Step 2A — Hidden check** — If the element is hidden (per `isHidden`) and NOT
+ *    referenced by `aria-labelledby`, return empty immediately.
+ * 2. **Pre-computed name** — (Implementation-specific extension) If the
+ *    resolver provides `getPrecomputedName`, check it before standard steps.
+ *    Used by ml-core's Pretender integration for framework components.
+ * 3. **Step 2B — `aria-labelledby`** — Resolve referenced elements and
+ *    recursively compute their names. Skipped when already inside a
+ *    labelledby traversal (`inLabelledbyTraversal`) to prevent re-entry.
+ * 4. **Step 2D — `aria-label`** — Use the `aria-label` attribute value.
+ * 5. **Step 2E — Element-specific name** — Dispatch to HTML-AAM §4.1
+ *    element-specific rules (label association, alt, value, legend, caption, SVG title).
+ * 6. **Step 2F — Name from content** — If the element's role allows
+ *    `nameFrom: ["content"]`, or the element is referenced by `aria-labelledby`
+ *    (`inLabelledbyTraversal`), recursively collect child text (including
+ *    embedded control values per Step 2C).
+ * 7. **Step 2I — Title fallback** — Use the `title` attribute value.
+ *
+ * @param el - The element to compute the accessible name for
+ * @param resolver - Environment-dependent resolver for DOM traversal and role queries
+ * @returns The computed name and its source
+ * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2
+ * @see https://www.w3.org/TR/html-aam-1.0/#accessible-name-and-description-computation — HTML-AAM §4.1
+ */
+export declare function computeAccessibleName(el: AccnameElement, resolver: AccnameResolver): AccnameResult;
+/**
+ * Internal recursive entry point for accessible name computation.
+ *
+ * This function is the recursive core called by `resolveAriaLabelledby` (Step 2B),
+ * `resolveLabelText` (Step 2E), and `resolveNameFromContent` (Step 2F) when they
+ * need to compute a child or referenced element's name.
+ *
+ * @param el - The element to compute the accessible name for
+ * @param resolver - Environment-dependent resolver for DOM traversal and role queries
+ * @param inLabelledbyTraversal - When true, Step 2B is skipped to prevent re-entry
+ *   into `resolveAriaLabelledby`, and Step 2F name-from-content is enabled regardless
+ *   of role. This is set by Step 2B when processing each IDREF.
+ * @param visited - Set of element IDs already visited (cycle prevention for aria-labelledby)
+ * @returns The computed name and its source
+ * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2
+ */
+export declare function computeAccessibleNameInternal(el: AccnameElement, resolver: AccnameResolver, inLabelledbyTraversal: boolean, visited: ReadonlySet<string>): AccnameResult;