@markuplint/rules 5.3.0 → 5.4.0

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.4.0](https://github.com/markuplint/markuplint/compare/v5.3.0...v5.4.0) (2026-10-29)
+
+### Bug Fixes
+
+* **rules:** do not report descendant attributes that take part in a text alternative ([46002a7](https://github.com/markuplint/markuplint/commit/46002a75e06f877938d134ce0958a625e5d989d3)), closes [#4408](https://github.com/markuplint/markuplint/issues/4408)
+
+
 # [5.3.0](https://github.com/markuplint/markuplint/compare/v5.2.0...v5.3.0) (2026-10-21)
 
 ### Bug Fixes

package/lib/no-aria-on-presentational-children/index.js

@@ -13,7 +13,9 @@ export default createRule({
                 return;
             if (!elSpec.globalAttrs['#ARIAAttrs'])
                 return;
-            report(checkingPresentationalChildren({ el }));
+            for (const attr of el.attributes) {
+                report(checkingPresentationalChildren({ attr, el }));
+            }
         });
     },
 });

package/lib/wai-aria/checkings/presentational-children.d.ts

@@ -1,8 +1,8 @@
 import type { Options } from '../types.js';
-import type { ElementChecker } from '@markuplint/ml-core';
+import type { AttrChecker, Element } from '@markuplint/ml-core';
 /**
- * Checks whether ARIA attributes are applied to descendants of an element whose
- * role has the `childrenArePresentational` characteristic.
+ * Checks whether an ARIA attribute or `role` is applied to a descendant of an
+ * element whose role has the `childrenArePresentational` characteristic.
  *
  * Presentational Children
  *
@@ -29,7 +29,18 @@ import type { ElementChecker } from '@markuplint/ml-core';
  * > can still be used in the name and description computation
  * > even when not included in the accessibility tree.
  *
- * @param el - The element node to inspect for presentational ancestor context.
- * @returns A violation if the element has ARIA attributes and an ancestor with presentational children.
+ * Because the text of the excluded descendants is still used, an attribute that
+ * changes what a descendant contributes to a text alternative is not
+ * ineffective, and is not reported (see {@link takesEffect}). The computations
+ * that can read the descendant are listed by {@link getVisits};
+ * `MLElement#getAccessibleNameVisits` tells which elements each of them reaches
+ * and how.
+ *
+ * @param attr - The attribute to inspect.
+ * @param el - The element the attribute is read on. For a pretended component it is
+ *   the component, while the attribute belongs to the element it pretends to be.
+ * @returns A violation if the attribute is an ARIA attribute or `role` that takes no effect under an ancestor with presentational children.
  */
-export declare const checkingPresentationalChildren: ElementChecker<boolean, Options>;
+export declare const checkingPresentationalChildren: AttrChecker<boolean, Options, {
+    readonly el: Element<boolean, Options>;
+}>;

package/lib/wai-aria/checkings/presentational-children.js

@@ -1,8 +1,8 @@
-import { isAriaAttr } from '../../helpers.js';
-import { ARIA_RECOMMENDED_VERSION, getComputedRole } from '@markuplint/ml-spec';
+import { isAriaAttr, labelable, memoizeByObject, namespaceKeyOf } from '../../helpers.js';
+import { ARIA_RECOMMENDED_VERSION, EMBEDDED_CONTROL_ROLES, getComputedRole, getImplicitRole, isExposedAsPresentational, isNativeEmbeddedControl, } from '@markuplint/ml-spec';
 /**
- * Checks whether ARIA attributes are applied to descendants of an element whose
- * role has the `childrenArePresentational` characteristic.
+ * Checks whether an ARIA attribute or `role` is applied to a descendant of an
+ * element whose role has the `childrenArePresentational` characteristic.
  *
  * Presentational Children
  *
@@ -29,44 +29,257 @@ import { ARIA_RECOMMENDED_VERSION, getComputedRole } from '@markuplint/ml-spec';
  * > can still be used in the name and description computation
  * > even when not included in the accessibility tree.
  *
- * @param el - The element node to inspect for presentational ancestor context.
- * @returns A violation if the element has ARIA attributes and an ancestor with presentational children.
+ * Because the text of the excluded descendants is still used, an attribute that
+ * changes what a descendant contributes to a text alternative is not
+ * ineffective, and is not reported (see {@link takesEffect}). The computations
+ * that can read the descendant are listed by {@link getVisits};
+ * `MLElement#getAccessibleNameVisits` tells which elements each of them reaches
+ * and how.
+ *
+ * @param attr - The attribute to inspect.
+ * @param el - The element the attribute is read on. For a pretended component it is
+ *   the component, while the attribute belongs to the element it pretends to be.
+ * @returns A violation if the attribute is an ARIA attribute or `role` that takes no effect under an ancestor with presentational children.
  */
-export const checkingPresentationalChildren = ({ el }) => t => {
-    const ancestor = getAncestorHasPresentationalChildren(el);
-    if (!ancestor) {
+export const checkingPresentationalChildren = ({ attr, el }) => t => {
+    if (!isAriaAttr(attr) && attr.nameKey !== 'role') {
         return;
     }
-    if (!ancestor.role) {
+    const context = getContext(el);
+    if (!context) {
         return;
     }
-    const hasAriaAttr = [...el.attributes].some(attr => isAriaAttr(attr) || attr.nameKey === 'role');
-    if (!hasAriaAttr) {
+    if (takesEffect(attr, el, context)) {
         return;
     }
     return {
-        scope: el,
-        message: t('it may be ineffective because {0}', t("it has {0} as an ancestor that doesn't expose its descendants to the accessibility tree", t('the "{0*}" {1}', ancestor.role.name, 'role'))),
+        scope: attr,
+        message: t('it may be ineffective because {0}', t("it has {0} as an ancestor that doesn't expose its descendants to the accessibility tree", t('the "{0*}" {1}', context.role.name, 'role'))),
     };
 };
 /**
- * Traverses the element's ancestor chain to find one whose computed role
- * has the `childrenArePresentational` characteristic.
+ * The closest ancestor role with presentational children, and the visits of the
+ * element by the computations that can read it, once per element.
+ */
+const getContext = memoizeByObject(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+(el) => {
+    const ariaVersion = el.rule.options?.version ?? el.ownerMLDocument.ruleCommonSettings?.ariaVersion ?? ARIA_RECOMMENDED_VERSION;
+    const role = getClosestPresentationalChildrenRole(el, ariaVersion);
+    if (!role) {
+        return null;
+    }
+    return { ariaVersion, role, visits: getVisits(el, ariaVersion) };
+});
+/**
+ * Finds the closest ancestor whose computed role has the
+ * `childrenArePresentational` characteristic.
  *
  * @param el - The element to start searching from (exclusive, starts from parent).
- * @returns The computed role of the ancestor with presentational children, or `null` if none found.
+ * @param ariaVersion - The ARIA version to compute the roles with.
+ * @returns The role of that ancestor, or `null` if none is found.
  */
-function getAncestorHasPresentationalChildren(
+function getClosestPresentationalChildrenRole(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-el) {
-    const ariaVersion = el.rule.options?.version ?? el.ownerMLDocument.ruleCommonSettings?.ariaVersion ?? ARIA_RECOMMENDED_VERSION;
+el, ariaVersion) {
     let current = el.parentElement;
     while (current) {
-        const computed = getComputedRole(el.ownerMLDocument.specs, current, ariaVersion);
-        if (computed.role?.childrenPresentational) {
-            return computed;
+        const role = getComputedRole(el.ownerMLDocument.specs, current, ariaVersion).role;
+        if (role?.childrenPresentational) {
+            return role;
         }
         current = current.parentElement;
     }
     return null;
 }
+/**
+ * The visits of the element by every computation that can read it. Each reader
+ * is taken whether or not its computation reaches the element; one that does
+ * not contributes no visit.
+ *
+ * - the accessible name of every ancestor, as any of them can collect the text
+ *   of its subtree (Step 2F and the recursion into descendants)
+ * - the text alternative of the element or of an ancestor as a node that
+ *   `aria-labelledby` or `aria-describedby` refers to
+ * - the accessible name of every control that a `label` ancestor can name: the
+ *   element its `for` refers to, and its labelable descendants (HTML-AAM)
+ *
+ * @see https://w3c.github.io/accname/#comp_name_from_content
+ * @see https://w3c.github.io/accname/#comp_labelledby_traversal
+ * @see https://w3c.github.io/html-aam/#accessible-name-and-description-computation
+ *
+ * @param el - The descendant
+ * @param ariaVersion - The ARIA version to compute the names with
+ * @returns The visits
+ */
+function getVisits(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, ariaVersion) {
+    const visits = [];
+    const add = (
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    reader, asReferenced = false) => {
+        visits.push(...(reader.getAccessibleNameVisits(ariaVersion, asReferenced).get(el) ?? []));
+    };
+    const document = el.ownerMLDocument;
+    const referenced = getReferencedIds(document);
+    let current = el;
+    while (current) {
+        if (current !== el) {
+            add(current);
+        }
+        if (current.id && referenced.has(current.id) && document.getElementById(current.id) === current) {
+            add(current, true);
+        }
+        for (const control of getLabeledControls(current)) {
+            add(control);
+        }
+        current = current.parentElement;
+    }
+    return visits;
+}
+/**
+ * The controls that the element can name if it is a `label`, as the accessible
+ * name computation finds labels: by `for` or as the closest `label` ancestor.
+ * Once per label.
+ *
+ * @see https://html.spec.whatwg.org/multipage/forms.html#labeled-control
+ */
+const getLabeledControls = memoizeByObject(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+(el) => {
+    if (el.localName !== 'label' || el.namespaceURI !== 'http://www.w3.org/1999/xhtml') {
+        return [];
+    }
+    const htmlFor = el.getAttribute('for');
+    const target = htmlFor == null ? null : el.ownerMLDocument.getElementById(htmlFor);
+    return [...(target ? [target] : []), ...el.querySelectorAll(labelable.join(', '))];
+});
+/**
+ * The IDs that an `aria-labelledby` or `aria-describedby` of the document refers to.
+ */
+const getReferencedIds = memoizeByObject(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+(document) => {
+    const ids = new Set();
+    for (const referrer of document.querySelectorAll('[aria-labelledby], [aria-describedby]')) {
+        for (const name of ['aria-labelledby', 'aria-describedby']) {
+            for (const id of referrer.getAttribute(name)?.split(/\s+/) ?? []) {
+                if (id !== '') {
+                    ids.add(id);
+                }
+            }
+        }
+    }
+    return ids;
+});
+/**
+ * Whether the attribute changes what its element contributes to a text
+ * alternative that reads it, given how the computations reach the element.
+ *
+ * - `aria-hidden="true"` makes the element hidden, so it and its subtree
+ *   contribute nothing (Step 2A), unless the `hidden` attribute hides it already
+ *   (the other way `@markuplint/ml-core` tells an element hidden).
+ * - An `aria-labelledby` replaces the element's subtree (Step 2B) when the
+ *   elements it refers to have any text, except inside an ongoing
+ *   `aria-labelledby` traversal.
+ * - A non-empty `aria-label` replaces it the same way (Step 2D), unless the
+ *   element is hidden, an `aria-labelledby` of it takes effect first (one that
+ *   refers to the element itself reads the `aria-label` again), or it is an
+ *   embedded control, whose `aria-label` the recursion ignores.
+ * - `role="none"` or `role="presentation"` drops the host language text
+ *   alternative of the element, such as the `alt` of an image (Step 2E), when the
+ *   element has one and the Presentational Roles Conflict Resolution does not
+ *   ignore the role.
+ * - A role that makes the element an embedded control, or keeps a native one
+ *   from being it, changes what it contributes between its value and its text
+ *   (Step 2C).
+ * - The `aria-valuetext`, or else the `aria-valuenow`, of a range embedded
+ *   control is its value (Step 2C).
+ *
+ * @see https://w3c.github.io/accname/#comp_embedded_control
+ * @see https://w3c.github.io/accname/#comp_hidden_not_referenced
+ * @see https://w3c.github.io/accname/#comp_labelledby
+ * @see https://w3c.github.io/accname/#comp_label
+ * @see https://w3c.github.io/accname/#comp_host_language_label
+ *
+ * > Otherwise, if the current node's native markup provides an attribute (e.g. alt) or element (e.g. HTML label or SVG title) that defines a text alternative, return that alternative in the form of a flat string as defined by the host language […], unless the current node is exposed as presentational (role="presentation" or role="none", alt="").
+ *
+ * @param attr - The attribute on a descendant of a presentational ancestor
+ * @param el - The descendant
+ * @param context - The ARIA version and the visits of the descendant
+ * @returns `true` if the attribute takes effect on a text alternative
+ */
+function takesEffect(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+attr, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, { ariaVersion, visits }) {
+    const shown = visits.filter(visit => !visit.hidden);
+    switch (namespaceKeyOf(attr)) {
+        case 'aria-hidden': {
+            return attr.value === 'true' && visits.some(visit => visit.hidden) && !el.hasAttribute('hidden');
+        }
+        case 'aria-labelledby': {
+            return labelledbyGivesText(el, ariaVersion) && shown.some(visit => !visit.inLabelledbyTraversal);
+        }
+        case 'aria-label': {
+            const overridden = labelledbyGivesText(el, ariaVersion) &&
+                !(el.id !== '' && el.getAttribute('aria-labelledby')?.split(/\s+/).includes(el.id));
+            return (attr.value.trim() !== '' &&
+                shown.some(visit => !visit.embeddedControl && (visit.inLabelledbyTraversal || !overridden)));
+        }
+        case 'aria-valuetext':
+        case 'aria-valuenow': {
+            // The value of a range embedded control: `aria-valuetext`, else `aria-valuenow`
+            const isRange = ['slider', 'spinbutton'].includes(el.getAttribute('role')?.trim().split(/\s+/)[0] ?? '') ||
+                (el.localName === 'input' && el.getAttribute('type')?.trim().toLowerCase() === 'range');
+            const valuetext = el.getAttribute('aria-valuetext')?.trim() ?? '';
+            const shadowed = namespaceKeyOf(attr) === 'aria-valuenow' && valuetext !== '';
+            // Step 2B comes first outside an ongoing aria-labelledby traversal
+            const labelledby = labelledbyGivesText(el, ariaVersion);
+            return (isRange &&
+                attr.value.trim() !== '' &&
+                !shadowed &&
+                shown.some(visit => visit.embeddedControl && (visit.inLabelledbyTraversal || !labelledby)));
+        }
+        case 'role': {
+            if (shown.length === 0) {
+                return false;
+            }
+            const { specs } = el.ownerMLDocument;
+            const computed = getComputedRole(specs, el, ariaVersion);
+            if (isEmbeddedControl(el, computed) !== isEmbeddedControl(el, getImplicitRole(specs, el, ariaVersion))) {
+                return true;
+            }
+            return (shown.some(visit => !visit.embeddedControl) &&
+                isExposedAsPresentational(computed) &&
+                el.getHostLanguageLabelSource(ariaVersion) !== null);
+        }
+    }
+    return false;
+}
+/**
+ * Whether the element is an embedded control with the role, as the resolver of
+ * `@markuplint/ml-core` tells it: by the role, or as a native control without one.
+ */
+function isEmbeddedControl(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, computed) {
+    return computed.role ? EMBEDDED_CONTROL_ROLES.has(computed.role.name) : isNativeEmbeddedControl(el);
+}
+/**
+ * Whether the `aria-labelledby` of the element gives a text: Step 2B returns the
+ * accumulated text of the elements it refers to only when that text is not empty.
+ */
+function labelledbyGivesText(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, ariaVersion) {
+    return (el.getAttribute('aria-labelledby')?.split(/\s+/) ?? []).some(id => {
+        if (id === '') {
+            return false;
+        }
+        const referenced = el.ownerMLDocument.getElementById(id);
+        return referenced != null && referenced.getReferencedTextAlternative(ariaVersion) !== '';
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/rules",
-	"version": "5.3.0",
+	"version": "5.4.0",
 	"description": "Built-in rules of markuplint",
 	"repository": {
 		"type": "git",
@@ -31,14 +31,14 @@
 		"./lib/permitted-contents/debug.js": "./lib/permitted-contents/debug.browser.js"
 	},
 	"dependencies": {
-		"@markuplint/html-spec": "5.3.0",
-		"@markuplint/ml-config": "5.3.0",
-		"@markuplint/ml-core": "5.3.0",
-		"@markuplint/ml-spec": "5.3.0",
-		"@markuplint/selector": "5.3.0",
-		"@markuplint/shared": "5.3.0",
-		"@markuplint/types": "5.3.0",
-		"@mdn/browser-compat-data": "^8.1.5",
+		"@markuplint/html-spec": "5.4.0",
+		"@markuplint/ml-config": "5.4.0",
+		"@markuplint/ml-core": "5.4.0",
+		"@markuplint/ml-spec": "5.4.0",
+		"@markuplint/selector": "5.4.0",
+		"@markuplint/shared": "5.4.0",
+		"@markuplint/types": "5.4.0",
+		"@mdn/browser-compat-data": "^8.1.6",
 		"@types/debug": "^4.1.13",
 		"ansi-colors": "^4.1.3",
 		"browserslist": "^4.29.3",
@@ -47,5 +47,5 @@
 		"image-size": "^2.0.4",
 		"type-fest": "^5.10.0"
 	},
-	"gitHead": "f587cf0206c8426e57369a48d6d5fb22306eafde"
+	"gitHead": "647f6fb5d5743f060678599c97e9c84b58970747"
 }