@markuplint/ml-spec 5.3.0 → 5.5.0

package/lib/algorithm/aria/get-computed-role.js

@@ -3,6 +3,7 @@ import { isPresentational } from './is-presentational.js';
 import { SVG_NAMESPACE } from '../../const/index.js';
 import { hasSvgAccessibleNameSource } from './accname/svg-helpers.js';
 import { getAttrSpecs } from '../../utils/get-attr-specs.js';
+import { getComposedParentElement } from '../dom/tree-boundary.js';
 import { getExplicitRole } from './get-explicit-role.js';
 import { getImplicitRole } from './get-implicit-role.js';
 import { getNonPresentationalAncestor } from './get-non-presentational-ancestor.js';
@@ -98,6 +99,7 @@ el, version, assumeSingleNode) {
      * "accessibility child" and "accessibility parent", and
      * `matchesContextRole` additionally skips `generic` elements.
      *
+     * @see https://w3c.github.io/aria/#conflict_resolution_presentation_none
      * @see https://w3c.github.io/aria/#scope
      * @see https://github.com/w3c/aria/issues/1033
      * @see https://github.com/w3c/aria/pull/1454
@@ -115,12 +117,14 @@ el, version, assumeSingleNode) {
         !isNativeContextIntact(computedRole, el, specs, version)) {
         /**
          * An element fragment that serves as the root without a parent element
-         * cannot satisfy the "Required Accessibility Parent Role" condition.
+         * (or the top of the content of an ordinary `template` element, whose
+         * placement is not known) cannot satisfy the "Required Accessibility
+         * Parent Role" condition.
          * Therefore, under normal circumstances, the `role` will disappear.
          * However, in this specific case, it will fall back to both explicit
          * and implicit roles. Note that the explicit role takes precedence.
          */
-        if (el.parentElement === null) {
+        if (getComposedParentElement(el) === null) {
             return {
                 ...computedRole,
                 errorType: 'NO_OWNER',
@@ -145,8 +149,7 @@ el, version, assumeSingleNode) {
     /**
      * SVG: Including Elements in the Accessibility Tree
      *
-     * > Many SVG elements—although rendered to the screen—
-     * > do not have an intrinsic semantic meaning. Instead,
+     * > Many SVG elements—although rendered to the screen—do not have an intrinsic semantic meaning. Instead,
      * > they represent components of the visual presentation of the document.
      * > To simplify the accessible representation of the document,
      * > these purely presentational elements should normally be omitted
@@ -166,15 +169,14 @@ el, version, assumeSingleNode) {
      * > - the use element
      * > - the grouping (g) element
      * > - the image element
-     * > - the mesh element
      * > - text formatting elements (textPath, tspan)
      * > - the foreignObject element
      *
-     * @see https://www.w3.org/TR/svg-aam-1.0/#include_elements
+     * @see https://www.w3.org/TR/svg-aam/#include_elements
      */
     if (
     // It doesn't been specified a valid explicit role.
-    (explicitRole.role === null || explicitRole.errorType != null) &&
+    explicitRole.role === null &&
         // It is an SVG element.
         el.namespaceURI === SVG_NAMESPACE &&
         !hasSvgAccessibleNameSource(el)) {
@@ -189,10 +191,12 @@ el, version, assumeSingleNode) {
     const implicitRole = lazyImplicitRole ?? getImplicitRole(specs, el, version);
     /**
      * > If an element is focusable,
-     * > user agents MUST ignore the presentation/none role
+     * > user agents MUST ignore the none/presentation role
      * > and expose the element with its implicit role,
      * > in order to ensure that the element is operable.
      *
+     * @see https://w3c.github.io/aria/#conflict_resolution_presentation_none
+     *
      * With the issue: What does focusable or otherwise interactive mean](https://github.com/w3c/aria/issues/1192)
      *
      * - Focus: https://html.spec.whatwg.org/multipage/interaction.html#focus
@@ -204,10 +208,9 @@ el, version, assumeSingleNode) {
      *
      * 1. It may be focusable
      *
-     * THIS CONDITION IS ALMOST MEANINGLESS.
-     * Because it has already been determined that
-     * the interactive elements can not specify the presentational role
-     * in the previous processing that computes the permitted role (`getExplicitRole`).
+     * ARIA in HTML does not permit the presentational roles on most
+     * interactive elements, but `getExplicitRole` keeps such a role with
+     * `NO_PERMITTED`, as user agents expose it, so this resolves it.
      */
     mayBeFocusable(el, specs) &&
         /**
@@ -287,6 +290,7 @@ el, specs, attrName) {
 }
 /**
  * Determines whether some ancestors match the condition that the specified callback function.
+ * The ancestors are those of the accessibility tree: see {@link getComposedParentElement}.
  */
 function someAncestors(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -295,7 +299,7 @@ el, predicate) {
     let current = el;
     while (current) {
         list.push(current);
-        current = current.parentElement;
+        current = getComposedParentElement(current);
     }
     return list.some(predicate);
 }
@@ -321,7 +325,7 @@ el, specs, version) {
     if (!computedRole.role?.isImplicit) {
         return false;
     }
-    const parent = el.parentElement;
+    const parent = getComposedParentElement(el);
     if (!parent) {
         return false;
     }

package/lib/algorithm/aria/get-explicit-role.d.ts

@@ -2,6 +2,12 @@ import type { ARIAVersion, ComputedRole, MLMLSpec } from '../../types/index.js';
 /**
  * Implements the WAI-ARIA "Handling Author Errors" algorithm.
  *
+ * The roles that ARIA in HTML does not permit on the element are authoring
+ * errors that the user agent does not correct: such a role is returned with
+ * `errorType: 'NO_PERMITTED'` (Core-AAM, the conflicts between the mappings), except on an element that is
+ * never rendered.
+ *
  * @see https://w3c.github.io/aria/#document-handling_author-errors
+ * @see https://w3c.github.io/core-aam/#mapping_conflicts — Core-AAM §3.2
  */
 export declare function getExplicitRole(specs: MLMLSpec, el: Element, version: ARIAVersion): ComputedRole;

package/lib/algorithm/aria/get-explicit-role.js

@@ -1,10 +1,18 @@
+import { decodeEntities } from '@markuplint/shared';
+import { XHTML_NAMESPACE } from '../../const/index.js';
 import { getRoleSpec } from './get-role-spec.js';
 import { resolveNamespace } from '../../utils/resolve-namespace.js';
 import { getPermittedRoles } from './get-permitted-roles.js';
 /**
  * Implements the WAI-ARIA "Handling Author Errors" algorithm.
  *
+ * The roles that ARIA in HTML does not permit on the element are authoring
+ * errors that the user agent does not correct: such a role is returned with
+ * `errorType: 'NO_PERMITTED'` (Core-AAM, the conflicts between the mappings), except on an element that is
+ * never rendered.
+ *
  * @see https://w3c.github.io/aria/#document-handling_author-errors
+ * @see https://w3c.github.io/core-aam/#mapping_conflicts — Core-AAM §3.2
  */
 export function getExplicitRole(specs, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -46,13 +54,6 @@ el, version) {
             error = 'ABSTRACT';
             continue;
         }
-        /**
-         * Whether the role is the permitted role according to ARIA in HTML.
-         */
-        if (!permittedRoles.some(r => r.name === roleName)) {
-            error = 'NO_PERMITTED';
-            continue;
-        }
         /**
          * > Certain landmark roles require names from authors.
          * > In situations where an author has not specified names for these landmarks,
@@ -66,6 +67,35 @@ el, version) {
             error = 'INVALID_LANDMARK';
             continue;
         }
+        /**
+         * A role that ARIA in HTML does not permit on the element is an
+         * authoring error, but user agents still expose it, so the role is
+         * kept and the error is reported alongside. An element that is never
+         * rendered is not in the accessibility tree at all (WAI-ARIA §7.1),
+         * so the role is dropped there.
+         *
+         * @see https://w3c.github.io/aria/#tree_exclusion
+         *
+         * > Elements, including their descendent elements, that have host language semantics specifying that the element is not displayed, such as CSS display:none, visibility:hidden, or the HTML hidden attribute.
+         *
+         * @see https://w3c.github.io/core-aam/#mapping_conflicts
+         *
+         * > While conformance checkers might signal an error or warning when a WAI-ARIA role is used on elements with strong native semantics, user agents MUST still use the value of the semantic of the WAI-ARIA role when exposing the element to accessibility APIs.
+         */
+        if (!permittedRoles.some(r => r.name === roleName)) {
+            if (isNeverRendered(el, namespaceURI)) {
+                error = 'NO_PERMITTED';
+                continue;
+            }
+            return {
+                el,
+                role: {
+                    ...spec,
+                    isImplicit: false,
+                },
+                errorType: 'NO_PERMITTED',
+            };
+        }
         /**
          * Otherwise
          */
@@ -83,6 +113,43 @@ el, version) {
         errorType: error,
     };
 }
+/**
+ * HTML elements that the user agent style sheet never renders (`display: none`),
+ * together with `input[type=hidden]` from the same rules (`isNeverRendered`).
+ * `area` is left out: it is rendered through its image map. The rules that
+ * depend on state (`[hidden]`, `noscript` with scripting) are left out too: the
+ * role stays on such an element, as its `hidden` attribute is a matter of the
+ * accessible name computation (Step 2A), not of the role.
+ *
+ * @see https://html.spec.whatwg.org/multipage/rendering.html#hidden-elements
+ */
+const NEVER_RENDERED_HTML_ELEMENTS = new Set([
+    'base',
+    'basefont',
+    'datalist',
+    'head',
+    'link',
+    'meta',
+    'noembed',
+    'noframes',
+    'param',
+    'rp',
+    'script',
+    'style',
+    'template',
+    'title',
+]);
+function isNeverRendered(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, namespaceURI) {
+    if (namespaceURI !== XHTML_NAMESPACE) {
+        return false;
+    }
+    if (NEVER_RENDERED_HTML_ELEMENTS.has(el.localName)) {
+        return true;
+    }
+    return el.localName === 'input' && el.getAttribute('type')?.trim().toLowerCase() === 'hidden';
+}
 function isLandmarkRole(role) {
     return role?.superClassRoles.some(su => su.name === 'landmark');
 }
@@ -96,8 +163,14 @@ el, role) {
         if (el.getAttribute('aria-label')) {
             return true;
         }
-        const id = el.getAttribute('aria-labelledby');
-        if (id && el.ownerDocument.getElementById(id)) {
+        // `aria-labelledby` is a list of ids, and each is resolved in the tree of the element: the
+        // content of a `template` element and a shadow root are trees of their own. A DOM has resolved the
+        // character references of a token already, but the markuplint DOM gives it as written in the markup,
+        // so the token is looked for as it is, and then with its character references resolved.
+        const ids = el.getAttribute('aria-labelledby')?.split(/\s+/).filter(Boolean) ?? [];
+        const root = el.getRootNode();
+        if ((root.nodeType === 9 || root.nodeType === 11) &&
+            ids.some(id => root.getElementById(id) ?? root.getElementById(decodeEntities(id)))) {
             return true;
         }
     }

package/lib/algorithm/aria/get-non-presentational-ancestor.d.ts

@@ -2,6 +2,8 @@ import type { ARIAVersion, MLMLSpec } from '../../types/index.js';
 /**
  * In ARIA 1.3, `generic` role elements are additionally transparent for
  * ownership traversal.
+ *
+ * The ancestors are those of the accessibility tree: see {@link getComposedParentElement}.
  */
 export declare function getNonPresentationalAncestor(el: Element, specs: MLMLSpec, version: ARIAVersion): import("../../types/index.js").ComputedRole | {
     el: null;

package/lib/algorithm/aria/get-non-presentational-ancestor.js

@@ -1,13 +1,16 @@
+import { getComposedParentElement } from '../dom/tree-boundary.js';
 import { isTransparentForOwnership } from './is-presentational.js';
 import { getComputedRole } from './get-computed-role.js';
 /**
  * In ARIA 1.3, `generic` role elements are additionally transparent for
  * ownership traversal.
+ *
+ * The ancestors are those of the accessibility tree: see {@link getComposedParentElement}.
  */
 export function getNonPresentationalAncestor(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, specs, version) {
-    let ancestor = el.parentElement;
+    let ancestor = getComposedParentElement(el);
     /**
      * In ARIA 1.1 and 1.2, the role of an element is not affected by the role of its ancestor elements.
      *
@@ -19,7 +22,7 @@ el, specs, version) {
         if (!isTransparentForOwnership(ancestorRole.role?.name, version)) {
             return ancestorRole;
         }
-        ancestor = ancestor.parentElement;
+        ancestor = getComposedParentElement(ancestor);
     }
     return {
         el: ancestor,

package/lib/algorithm/aria/is-exposed.d.ts

@@ -4,7 +4,9 @@ import type { ARIAVersion, MLMLSpec } from '../../types/index.js';
  * Applies WAI-ARIA exclusion/inclusion rules, SVG rendering rules, and
  * HTML metadata element filtering.
  *
- * @see https://www.w3.org/TR/wai-aria-1.2/#accessibility_tree
+ * The ancestors it reads are those of the accessibility tree ({@link getComposedParentElement}).
+ *
+ * @see https://w3c.github.io/aria/#accessibility_tree
  *
  * @param el - The DOM element to check for accessibility tree exposure
  * @param specs - The full markup language specification

package/lib/algorithm/aria/is-exposed.js

@@ -1,4 +1,5 @@
 import { ariaSpecs } from './aria-specs.js';
+import { getComposedParentElement } from '../dom/tree-boundary.js';
 import { getSpecByTagName } from '../../utils/get-spec-by-tag-name.js';
 import { isPresentational } from './is-presentational.js';
 import { resolveNamespace } from '../../utils/resolve-namespace.js';
@@ -8,7 +9,9 @@ import { getComputedRole } from './get-computed-role.js';
  * Applies WAI-ARIA exclusion/inclusion rules, SVG rendering rules, and
  * HTML metadata element filtering.
  *
- * @see https://www.w3.org/TR/wai-aria-1.2/#accessibility_tree
+ * The ancestors it reads are those of the accessibility tree ({@link getComposedParentElement}).
+ *
+ * @see https://w3c.github.io/aria/#accessibility_tree
  *
  * @param el - The DOM element to check for accessibility tree exposure
  * @param specs - The full markup language specification
@@ -47,7 +50,7 @@ el, specs, version) {
 /**
  * Excluding Elements from the Accessibility Tree
  *
- * @see https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion
+ * @see https://w3c.github.io/aria/#tree_exclusion
  *
  * @param specs
  * @param el
@@ -70,7 +73,7 @@ el, specs, version) {
             if (hasDisplayNodeOrVisibilityHidden(currentEl) || currentEl.hasAttribute('hidden')) {
                 return true;
             }
-            currentEl = currentEl.parentElement;
+            currentEl = getComposedParentElement(currentEl);
         }
     }
     /**
@@ -97,7 +100,7 @@ el, specs, version) {
             if (currentEl.getAttribute('aria-hidden') === 'true') {
                 return true;
             }
-            currentEl = currentEl.parentElement;
+            currentEl = getComposedParentElement(currentEl);
         }
     }
     /**
@@ -109,13 +112,13 @@ el, specs, version) {
      *   However, the text content of any excluded descendants is included.
      */
     {
-        let currentEl = el.parentElement;
+        let currentEl = getComposedParentElement(el);
         while (currentEl) {
             const { role } = getComputedRole(specs, currentEl, version);
             if (role?.childrenPresentational) {
                 return true;
             }
-            currentEl = currentEl.parentElement;
+            currentEl = getComposedParentElement(currentEl);
         }
     }
     return false;
@@ -128,7 +131,7 @@ el, specs, version) {
  * user agents MUST provide an accessible object in the accessibility tree
  * for DOM elements that meet any of the following criteria:
  *
- * @see https://www.w3.org/TR/wai-aria-1.2/#tree_inclusion
+ * @see https://w3c.github.io/aria/#tree_inclusion
  *
  * @param specs
  * @param el
@@ -172,6 +175,11 @@ el, specs, version) {
         }
         // Has a global WAI-ARIA attribute
         for (const attr of el.attributes) {
+            // An attribute that the host does not output (`MLAttr#isAbsent`, e.g. `aria-label={null}`)
+            // is not an attribute of the DOM
+            if (attr.isAbsent) {
+                continue;
+            }
             if (globalAria.some(aria => aria.name === attr.localName)) {
                 results.push(true);
                 break;

package/lib/algorithm/aria/is-presentational.d.ts

@@ -1,4 +1,4 @@
-import type { ARIAVersion } from '../../types/index.js';
+import type { ARIAVersion, ComputedRole } from '../../types/index.js';
 /**
  * Determines whether a given role name corresponds to a presentational role
  * (`"presentation"` or `"none"`), which indicates the element should be
@@ -8,6 +8,18 @@ import type { ARIAVersion } from '../../types/index.js';
  * @returns `true` if the role name is `"presentation"` or `"none"`, `false` otherwise
  */
 export declare function isPresentational(roleName?: string): boolean;
+/**
+ * Determines whether an element is exposed with the `none` or `presentation`
+ * role that its author specified, after the Presentational Roles Conflict
+ * Resolution. The implicit `presentation` role of `<img alt="">` does not count:
+ * HTML-AAM gives that image no name by its own rule.
+ *
+ * @see https://w3c.github.io/accname/#comp_host_language_label
+ *
+ * @param computed - The computed role of the element
+ * @returns `true` if the computed role is an explicit presentational role
+ */
+export declare function isExposedAsPresentational(computed: ComputedRole): boolean;
 /**
  * Determines whether a given role is transparent for ownership traversal.
  *
@@ -15,9 +27,8 @@ export declare function isPresentational(roleName?: string): boolean;
  * - **ARIA 1.1/1.2:** Only `presentation`/`none` are transparent.
  *   This matches the pre-existing behavior of `getClosestNonPresentationalDescendants`
  *   and `getNonPresentationalAncestor`.
- * - **ARIA 1.3:** `generic` is additionally transparent per the spec:
- *   "user agents MUST ignore any intervening elements with the role
- *   `generic` or `none`."
+ * - **ARIA 1.3:** `generic` is additionally transparent per the spec, which has
+ *   the user agent ignore the intervening elements with the role `generic` or `none`.
  *
  * **Note:** `matchesContextRole` calls this function unconditionally
  * (without a version gate) so that `presentation`/`none` are always

package/lib/algorithm/aria/is-presentational.js

@@ -12,6 +12,20 @@ export function isPresentational(roleName) {
     }
     return ['presentation', 'none'].includes(roleName);
 }
+/**
+ * Determines whether an element is exposed with the `none` or `presentation`
+ * role that its author specified, after the Presentational Roles Conflict
+ * Resolution. The implicit `presentation` role of `<img alt="">` does not count:
+ * HTML-AAM gives that image no name by its own rule.
+ *
+ * @see https://w3c.github.io/accname/#comp_host_language_label
+ *
+ * @param computed - The computed role of the element
+ * @returns `true` if the computed role is an explicit presentational role
+ */
+export function isExposedAsPresentational(computed) {
+    return !!computed.role && !computed.role.isImplicit && isPresentational(computed.role.name);
+}
 /**
  * Determines whether a given role is transparent for ownership traversal.
  *
@@ -19,9 +33,8 @@ export function isPresentational(roleName) {
  * - **ARIA 1.1/1.2:** Only `presentation`/`none` are transparent.
  *   This matches the pre-existing behavior of `getClosestNonPresentationalDescendants`
  *   and `getNonPresentationalAncestor`.
- * - **ARIA 1.3:** `generic` is additionally transparent per the spec:
- *   "user agents MUST ignore any intervening elements with the role
- *   `generic` or `none`."
+ * - **ARIA 1.3:** `generic` is additionally transparent per the spec, which has
+ *   the user agent ignore the intervening elements with the role `generic` or `none`.
  *
  * **Note:** `matchesContextRole` calls this function unconditionally
  * (without a version gate) so that `presentation`/`none` are always

package/lib/algorithm/aria/matches-context-role.d.ts

@@ -4,11 +4,13 @@ import type { ARIAVersion, MLMLSpec } from '../../types/index.js';
  * Context Role" in ARIA 1.2). Each condition string describes a chain of
  * ancestor roles separated by ` > ` (e.g., `"list > group"`).
  *
- * TODO: This function only walks the DOM `parentElement` chain and does not
+ * TODO: This function only walks the composed parent chain and does not
  * consider `aria-owns` relationships. An element referenced by `aria-owns` on
  * a remote ancestor should be treated as if it were an accessibility child of
  * that ancestor. Implementing this requires a document-wide reverse lookup of
  * `aria-owns` attributes, which is a separate architectural concern.
  * See also: `has-required-owned-elements.ts` has a similar limitation.
+ *
+ * The chain is the one the accessibility tree is built from ({@link getComposedParentElement}).
  */
 export declare function matchesContextRole(conditions: readonly string[], ownedEl: Element, specs: MLMLSpec, version: ARIAVersion): boolean;

package/lib/algorithm/aria/matches-context-role.js

@@ -1,3 +1,4 @@
+import { getComposedParentElement } from '../dom/tree-boundary.js';
 import { isTransparentForOwnership } from './is-presentational.js';
 import { getComputedRole } from './get-computed-role.js';
 /**
@@ -5,17 +6,19 @@ import { getComputedRole } from './get-computed-role.js';
  * Context Role" in ARIA 1.2). Each condition string describes a chain of
  * ancestor roles separated by ` > ` (e.g., `"list > group"`).
  *
- * TODO: This function only walks the DOM `parentElement` chain and does not
+ * TODO: This function only walks the composed parent chain and does not
  * consider `aria-owns` relationships. An element referenced by `aria-owns` on
  * a remote ancestor should be treated as if it were an accessibility child of
  * that ancestor. Implementing this requires a document-wide reverse lookup of
  * `aria-owns` attributes, which is a separate architectural concern.
  * See also: `has-required-owned-elements.ts` has a similar limitation.
+ *
+ * The chain is the one the accessibility tree is built from ({@link getComposedParentElement}).
  */
 export function matchesContextRole(conditions, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 ownedEl, specs, version) {
-    return conditions.some(condition => matchesCondition(condition, ownedEl.parentElement, specs, version));
+    return conditions.some(condition => matchesCondition(condition, getComposedParentElement(ownedEl), specs, version));
 }
 function matchesCondition(condition, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -27,9 +30,9 @@ parentEl, specs, version) {
         }
         const parentRole = getComputedRole(specs, parentEl, version, true).role;
         /**
-         * ARIA 1.3 ("Required Accessibility Parent Role"): "To determine
-         * whether an element has a parent with the required role, user agents
-         * MUST ignore any elements with the role `generic` or `none`."
+         * ARIA 1.3 (Required Accessibility Parent Role): to determine whether an
+         * element has a parent with the required role, the user agent ignores the
+         * elements with the role `generic` or `none`.
          *
          * `presentation`/`none` are transparent in all ARIA versions to stay
          * consistent with `getNonPresentationalAncestor` (which already skips
@@ -47,14 +50,14 @@ parentEl, specs, version) {
          * @see https://w3c.github.io/aria/#scope
          */
         if (isTransparentForOwnership(parentRole?.name, version)) {
-            parentEl = parentEl.parentElement;
+            parentEl = getComposedParentElement(parentEl);
             continue;
         }
         const condition = conditions.shift();
         if (condition !== parentRole?.name) {
             return false;
         }
-        parentEl = parentEl.parentElement;
+        parentEl = getComposedParentElement(parentEl);
     }
     return true;
 }

package/lib/algorithm/dom/tree-boundary.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @module
+ *
+ * The parent of an element as the DOM sees it, for the algorithms that walk up from an element.
+ *
+ * The algorithms of this package are written against the DOM `Element`, where `parentElement`
+ * stops at the boundary of a tree: the parent element of a node whose parent is not an element
+ * (a document fragment, such as the content of a `template` element or a shadow root) is `null`.
+ * `@markuplint/ml-core` hands them its own elements, whose `parentElement` is the syntactical
+ * parent: the syntax tree has no other place for the content of a `template` element than its
+ * children, so the top of the content has the `template` element as its parent element. A walk
+ * that reads `parentElement` there leaves the content and enters the tree that holds the
+ * `template`. `getRootNode()` is where `@markuplint/ml-core` puts the boundary, and in a real DOM
+ * a parent is always in the tree of its child, so comparing the two roots gives the DOM's answer
+ * to both.
+ *
+ * This package cannot use `MLNode#treeParentElement` of `@markuplint/ml-core`, which depends on it,
+ * so the helpers derive the same answer from `getRootNode()`. The two are pinned to agree by
+ * `tree-scope.spec.ts` of `@markuplint/ml-core`: a change to the boundary in one belongs to both.
+ *
+ * Which of the two helpers a walk takes depends on what it follows:
+ *
+ * - {@link getTreeParentElement} follows a relation that the DOM defines in the tree, such as
+ *   the ancestor `label` element of a labelable element (`findAncestorLabel`, the one walk of
+ *   this package that does not follow the accessibility tree).
+ * - {@link getComposedParentElement} follows what the accessibility tree is built from. Its
+ *   content is the flat tree: the content of a shadow root is rendered in its host, so the
+ *   elements above it are the host and the ancestors of the host. The content of an ordinary
+ *   `template` element is not rendered, and where it is inserted is not known from the markup,
+ *   so a walk ends at its top.
+ *
+ * A `template` element that may have a declarative shadow root but whose attachment is not known
+ * from the markup (a host that is not in the file, a component, or a dynamic `shadowrootmode`),
+ * or that fails to attach one, is treated as an ordinary `template` element: a walk ends at the
+ * top of its content.
+ *
+ * Known limitation: the flat tree places the content of a shadow root where the `slot` element
+ * is, between the host and the nodes the host has as children. A walk goes from the top of the
+ * shadow root to the host and does not model the position of the `slot`.
+ *
+ * @see https://dom.spec.whatwg.org/#parent-element
+ * @see https://dom.spec.whatwg.org/#concept-shadow-including-ancestor
+ * @see https://html.spec.whatwg.org/multipage/scripting.html#the-template-element
+ */
+/**
+ * What the helpers read of an element: the DOM `Element`, and `MLElement` of `@markuplint/ml-core`.
+ * An element without `getRootNode` (an adapter that has no notion of a tree boundary) is in one
+ * tree with its parent element.
+ */
+type TreeElement = {
+    readonly parentElement: unknown;
+    getRootNode?(): unknown;
+};
+/**
+ * The parent element of an element in its own tree, which is what the DOM calls `parentElement`:
+ * `null` at the top of the content of a `template` element or of a shadow root, even where the
+ * `parentElement` of the element implementation is the `template` element.
+ *
+ * @template P - The type of the parent element the element reads
+ * @param el - The element to start from
+ * @returns The parent element, or `null` when the element is at the top of its tree
+ */
+export declare function getTreeParentElement<P extends TreeElement>(el: {
+    readonly parentElement: P | null;
+    getRootNode?(): unknown;
+}): P | null;
+/**
+ * The parent element of an element as the accessibility tree is built: the parent element in its own
+ * tree, or, at the top of a shadow root, the host of the shadow root. `null` at the top of the content
+ * of an ordinary `template` element, and at the top of a document or of any other root that is not a
+ * shadow root.
+ *
+ * @template P - The type of the parent element the element reads
+ * @param el - The element to start from
+ * @returns The parent element or the shadow host, or `null` when the walk ends
+ */
+export declare function getComposedParentElement<P extends TreeElement>(el: {
+    readonly parentElement: P | null;
+    getRootNode?(): unknown;
+}): P | null;
+/**
+ * Whether a root is a shadow root: a document fragment that has a host.
+ * The shadow root of `@markuplint/ml-core` is not a `ShadowRoot` of the DOM by class, and the
+ * content of an ordinary `template` element is a document fragment that has no host.
+ *
+ * @template P - The type of the host
+ * @param root - The root of a tree
+ * @returns `true` if the root has a host element
+ */
+export declare function isShadowRoot<P = unknown>(root: unknown): root is {
+    readonly host: P;
+};
+export {};