@markuplint/ml-spec 5.4.0 → 5.5.0

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

@@ -31,7 +31,7 @@ const computingElements = new WeakSet();
  * @param specs - The ML specification data for role resolution
  * @param version - The ARIA version to use for role computation
  * @returns The computed accessible name string, or an empty string if none is found
- * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2
+ * @see https://w3c.github.io/accname/#computation-steps — AccName 1.2 §4.3.2
  */
 export function getAccname(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -130,15 +130,15 @@ el, specs, version) {
     };
 }
 /**
- * Walks up the DOM tree to find the root node (Document or DocumentFragment).
+ * Finds the root node (Document or DocumentFragment) of the tree the element is in: for an
+ * element in the content of a `template` element or a shadow root, that content, not the
+ * document. A host that holds the content in the syntax tree under the `template` element (the
+ * markuplint DOM) answers it in `getRootNode()`, as the DOM does.
  */
 function getRootNode(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el) {
-    let root = el;
-    while (root.parentNode) {
-        root = root.parentNode;
-    }
+    const root = el.getRootNode();
     if (root.nodeType === 9 || root.nodeType === 11) {
         return root;
     }

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

@@ -89,14 +89,14 @@ function optimizePermittedRoles(permittedRoles, version) {
         return permittedRoles;
     }
     const unique = new Set(permittedRoles);
-    // https://www.w3.org/TR/wai-aria-1.2/#note-regarding-the-aria-1-1-none-role
+    // https://w3c.github.io/aria/#none
     if (unique.has('presentation')) {
         unique.add('none');
     }
     if (unique.has('none')) {
         unique.add('presentation');
     }
-    // https://w3c.github.io/aria/#ref-for-image
+    // https://w3c.github.io/aria/#image
     // In ARIA 1.3, `image` is the primary role name and `img` is a synonym.
     if (version === '1.3') {
         if (unique.has('image')) {

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,11 +169,10 @@ 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.
@@ -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
@@ -286,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
@@ -294,7 +299,7 @@ el, predicate) {
     let current = el;
     while (current) {
         list.push(current);
-        current = current.parentElement;
+        current = getComposedParentElement(current);
     }
     return list.some(predicate);
 }
@@ -320,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

@@ -4,10 +4,10 @@ import type { ARIAVersion, ComputedRole, MLMLSpec } from '../../types/index.js';
  *
  * 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 §3.2), except on an element that is
+ * `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
+ * @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,3 +1,4 @@
+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';
@@ -7,11 +8,11 @@ import { getPermittedRoles } from './get-permitted-roles.js';
  *
  * 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 §3.2), except on an element that is
+ * `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
+ * @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
@@ -162,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

@@ -27,9 +27,8 @@ export declare function isExposedAsPresentational(computed: ComputedRole): boole
  * - **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

@@ -33,9 +33,8 @@ export function isExposedAsPresentational(computed) {
  * - **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 {};

package/lib/algorithm/dom/tree-boundary.js

@@ -0,0 +1,103 @@
+/**
+ * @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
+ */
+/** DOM `Node.DOCUMENT_FRAGMENT_NODE` */
+const DOCUMENT_FRAGMENT_NODE = 11;
+/**
+ * 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 function getTreeParentElement(el) {
+    const parent = el.parentElement;
+    if (!parent) {
+        return null;
+    }
+    // Without a tree on either side there is no boundary between them
+    if (!parent.getRootNode || !el.getRootNode) {
+        return parent;
+    }
+    return parent.getRootNode() === el.getRootNode() ? parent : 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 function getComposedParentElement(el) {
+    const parent = getTreeParentElement(el);
+    if (parent) {
+        return parent;
+    }
+    const root = el.getRootNode?.();
+    if (isShadowRoot(root)) {
+        return root.host;
+    }
+    return 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 function isShadowRoot(root) {
+    return (typeof root === 'object' &&
+        root !== null &&
+        'nodeType' in root &&
+        root.nodeType === DOCUMENT_FRAGMENT_NODE &&
+        'host' in root);
+}

package/lib/algorithm/html/content-model-category-to-tag-names.d.ts

@@ -6,9 +6,13 @@ import type { Category } from '../../types/permitted-structures.js';
  * Results are cached for repeated lookups.
  *
  * Note: entries are returned as stored in the spec's `#contentModels` map
- * without CSS selector parsing — they are expected to be bare tag names or
- * tag-with-attribute selectors (e.g. `a[href]`); complex selectors are not
- * decomposed into tag names.
+ * without CSS selector parsing. Besides bare tag names they include selectors
+ * (`a[href]`, `hgroup:has(h1,h2,h3,h4,h5,h6)`, `style:first-child`), which are
+ * not decomposed into tag names; `#custom` and `#text` stand for custom elements
+ * and text. An entry ending in `:first-child` holds as the first child as the HTML
+ * Standard counts it, text included, which markuplint's own paths match with
+ * `contentModelFirstChildBase` and `isContentModelFirstChild` of
+ * `@markuplint/selector`; matched as a plain selector, it counts elements only.
  *
  * @param contentModel - The content model category identifier
  * @param def - The specification definitions containing content model mappings