@markuplint/ml-core 5.1.1 → 5.3.0

package/lib/ml-dom/node/attr.js

@@ -1,9 +1,10 @@
 import { resolveNamespace, compileDirectivePatterns, resolveDirective } from '@markuplint/ml-spec';
-import { searchIDLAttribute } from '@markuplint/parser-utils';
+import { searchIDLAttribute, suggestIDLAttribute } from '@markuplint/parser-utils';
+import { adjustForeignAttrName } from '../helper/foreign-attr-names.js';
 import { MLToken } from '../token/token.js';
 import { MLDomTokenList } from './dom-token-list.js';
 import { MLNode } from './node.js';
-import { UnexpectedCallError } from '@markuplint/shared';
+import { UnexpectedCallError, asciiLowerCase, vuePropKey } from '@markuplint/shared';
 /**
  * Represents a DOM Attr (attribute) node wrapper in the markuplint DOM tree.
  * Wraps an AST attribute token and provides access to the attribute's name, value,
@@ -90,7 +91,7 @@ export class MLAttr extends MLNode {
         super(astToken, ownElement.ownerMLDocument);
         this.ownerElement = ownElement;
         if (this._astToken.type === 'spread') {
-            this.#namespaceURI = ownElement.namespaceURI;
+            this.#namespaceURI = null;
             this.valueType = 'code';
             this.#localName = '#spread';
             this.#potentialName = '#spread';
@@ -141,10 +142,12 @@ export class MLAttr extends MLNode {
                 }
                 // Set candidate for IDL naming suggestions (e.g., tabindex → tabIndex in JSX).
                 // Only in 'idl' mode (React). In 'both' mode (Svelte), both content and IDL names are accepted.
-                if (!resolution && idlPropName && ownElement.ownerMLDocument.specs.acceptedAttrNames === 'idl') {
+                if (!resolution && ownElement.ownerMLDocument.specs.acceptedAttrNames === 'idl') {
+                    // The property of a spelling that is not its own (`TABINDEX`) is suggested as well
+                    const suggested = idlPropName ?? suggestIDLAttribute(this.#potentialName);
                     const rawName = this.nameNode?.raw ?? '';
-                    if (rawName !== idlPropName) {
-                        this.candidate = idlPropName;
+                    if (suggested && rawName !== suggested) {
+                        this.candidate = suggested;
                     }
                 }
             }
@@ -156,9 +159,18 @@ export class MLAttr extends MLNode {
             this.isDirective = this._astToken.isDirective;
             this.isDuplicatable = this._astToken.isDuplicatable;
         }
-        const ns = resolveNamespace(this.#potentialName, ownElement.namespaceURI);
+        // The HTML parser lower-cases the name before it adjusts a foreign attribute, so `XLINK:HREF`
+        // is `xlink:href` there; a name that code sets keeps the case of its prefix.
+        const prefixed = this.#potentialName.includes(':') && !this.isSetThroughDOMAPI;
+        const nameWithPrefix = prefixed ? asciiLowerCase(this.#potentialName) : this.#potentialName;
+        const ns = resolveNamespace(nameWithPrefix, ownElement.namespaceURI);
         this.#localName = ns.localName;
-        this.#namespaceURI = ns.namespaceURI;
+        // An attribute does not inherit the namespace of its element, so only a known prefix
+        // gives it one. `ns.namespace` equals the prefix exactly when the prefix is a known
+        // one; for an unknown prefix it falls back to the element's namespace.
+        const hasPrefix = ns.localName !== nameWithPrefix;
+        const prefix = nameWithPrefix.split(':')[0];
+        this.#namespaceURI = hasPrefix && ns.namespace === prefix ? ns.namespaceURI : null;
     }
     /**
      * Returns the local name portion of the attribute (without namespace prefix).
@@ -179,7 +191,136 @@ export class MLAttr extends MLNode {
         return this.#potentialName;
     }
     /**
-     * Returns the namespace URI of this attribute, resolved from the attribute name.
+     * The name that the DOM gives this attribute, which two spellings of a name share when they are
+     * one attribute (`ID` and `id` on a `<div>`, `VIEWBOX` and `viewbox` on an `<svg>` that the
+     * HTML parser reads). `name` keeps the spelling of the source for a message, and for
+     * `case-sensitive-attr-name`.
+     *
+     * It depends on how the name gets into the DOM (`MLDocument#attrNameRoute`) and on the element:
+     * the HTML parser lower-cases a name, and restores the case of the names of SVG and MathML;
+     * `setAttribute` lower-cases a name only on an element of the HTML namespace, so `ROLE` on an
+     * `<svg>` that code sets is `ROLE`, which is not `role`. The attribute of a component is a prop,
+     * which keeps its spelling, except in Vue where `my-label` and `myLabel` are one prop.
+     *
+     * @see https://dom.spec.whatwg.org/#dom-element-setattribute
+     * @see https://html.spec.whatwg.org/multipage/parsing.html#attribute-name-state
+     */
+    get nameKey() {
+        return this.keyOf(this.#potentialName);
+    }
+    /**
+     * The key of `name`, a name of a spec, of an option or of a lookup, as this attribute is keyed:
+     * `name` is this attribute when its key is {@link MLAttr.nameKey}. Only the ASCII letters fold,
+     * as the HTML syntax says (`toLowerCase` also turns U+212A KELVIN SIGN into `k`).
+     *
+     * It is computed when asked, not stored by the constructor: it reads the owner element (its
+     * type and namespace) and the document, which are complete only after the attribute is built.
+     *
+     * @param name - A name as written
+     * @returns The key that two spellings of one attribute share
+     */
+    keyOf(name) {
+        const el = this.ownerElement;
+        if (el.elementType === 'authored') {
+            return el.ownerMLDocument.componentNameVariants ? vuePropKey(name) : name;
+        }
+        if (!el.isForeignElement) {
+            return asciiLowerCase(name);
+        }
+        if (this.isSetThroughDOMAPI) {
+            return name;
+        }
+        return adjustForeignAttrName(asciiLowerCase(name), el.namespaceURI);
+    }
+    /**
+     * Whether `name` is the name of this attribute: the spelling it is written in, or another that
+     * the DOM makes the same attribute ({@link MLAttr.keyOf}). A spec, an option and the lookups of
+     * the element ask this, so the case of a name is decided here and not in each of them.
+     *
+     * A name with a capital letter that code sets on an element of the HTML namespace is a prop of
+     * the framework (`defaultValue` of React), not an attribute of the DOM: only its exact spelling
+     * is it, and `defaultvalue` is not (see {@link MLAttr.isPrefixedBy} for a prefix).
+     *
+     * @param name - A name of a spec, an option or a lookup
+     * @returns `true` if `name` is this attribute
+     */
+    isNamedBy(name) {
+        if (name === this.#potentialName) {
+            return true;
+        }
+        if (this.#isFrameworkPropName(name)) {
+            return false;
+        }
+        return this.keyOf(name) === this.nameKey;
+    }
+    /**
+     * Whether the name of this attribute starts with `prefix`, a prefix of an option
+     * (`ignoreAttrNamePrefix`): as it is written, or as the DOM gives the name ({@link MLAttr.keyOf}).
+     * A prefix with a capital letter that code sets on an element of the HTML namespace is the prefix
+     * of a name of the framework, and only its exact spelling is it, as for {@link MLAttr.isNamedBy}.
+     *
+     * @param prefix - A prefix of an option
+     * @returns `true` if the name of this attribute starts with `prefix`
+     */
+    isPrefixedBy(prefix) {
+        if (this.#potentialName.startsWith(prefix)) {
+            return true;
+        }
+        if (this.#isFrameworkPropName(prefix)) {
+            return false;
+        }
+        return this.nameKey.startsWith(this.keyOf(prefix));
+    }
+    /**
+     * A name with a capital letter that code sets on an element of the HTML namespace is a prop of the
+     * framework (`defaultValue` of React), not an attribute of the DOM: the DOM folds what `setAttribute`
+     * is given, and a prop is read as it is written.
+     */
+    #isFrameworkPropName(name) {
+        const el = this.ownerElement;
+        return el.elementType !== 'authored' && !el.isForeignElement && this.isSetThroughDOMAPI && /[A-Z]/.test(name);
+    }
+    /**
+     * Whether the name of this attribute reaches the DOM through the DOM API (`setAttribute`) and
+     * not through the HTML parser of the browser: what the parser says of its language
+     * (`MLDocument#attrNameRoute`), and for a parser that says it of a dynamic attribute only
+     * (Svelte), whether this one is dynamic.
+     */
+    get isSetThroughDOMAPI() {
+        const route = this.ownerElement.ownerMLDocument.attrNameRoute;
+        return route === 'dom-api' || (route === 'dom-api-when-dynamic' && this.isDynamicValue === true);
+    }
+    /**
+     * Whether a selector matches the name of this attribute without regard to ASCII case: the DOM
+     * does so for an element of the HTML namespace and not for one of SVG or MathML, nor for a prop.
+     *
+     * @implements `SelectorAttr#nameCaseInsensitive` of `@markuplint/selector`
+     */
+    get nameCaseInsensitive() {
+        const el = this.ownerElement;
+        return el.elementType !== 'authored' && !el.isForeignElement;
+    }
+    /**
+     * The name that a selector is matched with.
+     *
+     * @implements `SelectorAttr#domName` of `@markuplint/selector`
+     */
+    get domName() {
+        return this.nameKey;
+    }
+    /**
+     * Whether a name of a selector is this prop once it is camelized: the props of a Vue component.
+     *
+     * @implements `SelectorAttr#nameIsCamelized` of `@markuplint/selector`
+     */
+    get nameIsCamelized() {
+        const el = this.ownerElement;
+        return el.elementType === 'authored' && el.ownerMLDocument.componentNameVariants;
+    }
+    /**
+     * Returns the namespace URI of this attribute: that of its prefix when the name has a known
+     * one (e.g. `xlink:href`), otherwise `null`. An attribute without a prefix has no namespace
+     * whichever element it is on, and so does a spread attribute.
      *
      * @implements DOM API: `Attr`
      * @see https://dom.spec.whatwg.org/#ref-for-dom-attr-namespaceuri

package/lib/ml-dom/node/document.d.ts

@@ -10,7 +10,7 @@ import type { Ruleset } from '../../ruleset/index.js';
 import type { MLSchema } from '../../types.js';
 import type { Walker } from '../helper/walkers.js';
 import type { MLToken } from '../token/token.js';
-import type { EndTagType, MLASTDocument, MLASTNodeTreeItem, MLASTParseError } from '@markuplint/ml-ast';
+import type { AttrNameRoute, EndTagType, MLASTDocument, MLASTNodeTreeItem, MLASTParseError } from '@markuplint/ml-ast';
 import type { PlainData, Pretender, RuleCommonSettings, RuleConfigValue } from '@markuplint/ml-config';
 import type { ARIAVersion, MLMLSpec } from '@markuplint/ml-spec';
 import { MLParentNode } from './parent-node.js';
@@ -74,6 +74,53 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
      * When false (default for HTML), tag names are compared case-insensitively.
      */
     readonly tagNameCaseSensitive: boolean;
+    /**
+     * Whether a component is referred to by any spelling of its name: `<FooBar>`, `<fooBar>` and
+     * `<foo-bar>` are one component (Vue). A type selector reads it through
+     * {@link MLElement.tagNameKind}.
+     */
+    readonly componentNameVariants: boolean;
+    /**
+     * Whether a name is a reference to a component, not the name of an element, judged by its form
+     * alone in the language of the parser (`Tabs.Root` is, `div` is not). The target of a pretender
+     * is typed by it. It is the rule of the parser (`MLParser#isComponentName`, a method of the parser's
+     * class, not of this one); the form that most languages share (`isComponentName` of
+     * `@markuplint/parser-utils`) when the parser has none.
+     */
+    readonly isComponentName: (name: string) => boolean;
+    /**
+     * Whether a tag is a native element: the rule of the parser (`MLParser#isNativeTag`) when it has one, which
+     * takes the name as written and knows no namespace, else the specification (`getSpecByTagName`) of the
+     * name in its namespace. {@link MLElement.tagNameKind} and the guard of {@link MLElement.pretending}
+     * read it, so that a type selector and a pretender agree on what a tag is.
+     *
+     * Rules keyed on the specification (deprecated / obsolete elements) do not read it. Nor does the
+     * element that a pretender stands for (`as`): the name is the element itself there, not a tag to resolve,
+     * so it is judged by the specification and never passes through this method.
+     *
+     * @param localName - The name of the tag as the author wrote it, never the `as` of a pretender
+     * @param namespaceURI - The namespace of the element; not read when the parser has a rule, as Vue's is the same for every namespace
+     * @returns Whether the document takes the tag for a native element
+     */
+    isNativeTag(localName: string, namespaceURI: string): boolean;
+    /**
+     * Whether attribute names are JavaScript identifiers in the source language (JSX props such as
+     * `onClick`), which the `case-sensitive-attr-name` rule does not ask to be lower case.
+     *
+     * It says nothing about whether two spellings of a name are one attribute: that is up to how the
+     * name gets into the DOM ({@link MLDocument.attrNameRoute}) and to the element, and is decided by
+     * {@link MLAttr.nameKey}. Svelte and Astro tell the case of a tag name apart but not of an
+     * attribute name, and Vue sets its attributes through the DOM API though a template is still
+     * checked for the case of a name.
+     */
+    readonly attrNameCaseSensitive: boolean;
+    /**
+     * How the name of an attribute gets into the DOM of the browser (`MLParser#attrNameRoute`, see
+     * `AttrNameRoute`). It decides whether `VIEWBOX` and `viewBox` are one attribute, which is a matter of the
+     * DOM and so of the element and the attribute as well; this is what the parser says about its language.
+     * `"html-parser"` when the parser does not say.
+     */
+    readonly attrNameRoute: AttrNameRoute;
     /**
      * Common settings applied globally to all rules, such as the ARIA version.
      * Rules use this as a fallback when their own options do not specify a value.
@@ -91,6 +138,11 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
         readonly endTag?: 'xml' | 'omittable' | 'never';
         readonly booleanish?: boolean;
         readonly tagNameCaseSensitive?: boolean;
+        readonly componentNameVariants?: boolean;
+        readonly isComponentName?: (name: string) => boolean;
+        readonly isNativeTag?: (name: string) => boolean;
+        readonly attrNameCaseSensitive?: boolean;
+        readonly attrNameRoute?: AttrNameRoute;
         readonly pretenders?: readonly Pretender[];
     });
     /**

package/lib/ml-dom/node/document.js

@@ -1,6 +1,6 @@
 import { exchangeValueOnRule, mergeRule } from '@markuplint/ml-config';
-import { schemaToSpec, getComputedRole, mayBeFocusable, getComputedAriaProps, isExposed, ARIA_RECOMMENDED_VERSION, } from '@markuplint/ml-spec';
-import { ConfigParserError } from '@markuplint/parser-utils';
+import { schemaToSpec, getComputedRole, mayBeFocusable, getComputedAriaProps, isExposed, getSpecByTagName, ARIA_RECOMMENDED_VERSION, } from '@markuplint/ml-spec';
+import { ConfigParserError, isComponentName } from '@markuplint/parser-utils';
 import { InvalidSelectorError } from '@markuplint/selector';
 import { log as coreLog } from '../../debug.js';
 import { createNode } from '../helper/create-node.js';
@@ -50,6 +50,7 @@ export class MLDocument extends MLParentNode {
     endTag;
     #astNodeMap;
     #filename;
+    #isNativeTagRule;
     /**
      * Whether this document represents a fragment rather than a complete document.
      * Fragment documents may lack root-level elements like `<html>`, `<head>`, or `<body>`.
@@ -74,6 +75,58 @@ export class MLDocument extends MLParentNode {
      * When false (default for HTML), tag names are compared case-insensitively.
      */
     tagNameCaseSensitive;
+    /**
+     * Whether a component is referred to by any spelling of its name: `<FooBar>`, `<fooBar>` and
+     * `<foo-bar>` are one component (Vue). A type selector reads it through
+     * {@link MLElement.tagNameKind}.
+     */
+    componentNameVariants;
+    /**
+     * Whether a name is a reference to a component, not the name of an element, judged by its form
+     * alone in the language of the parser (`Tabs.Root` is, `div` is not). The target of a pretender
+     * is typed by it. It is the rule of the parser (`MLParser#isComponentName`, a method of the parser's
+     * class, not of this one); the form that most languages share (`isComponentName` of
+     * `@markuplint/parser-utils`) when the parser has none.
+     */
+    isComponentName;
+    /**
+     * Whether a tag is a native element: the rule of the parser (`MLParser#isNativeTag`) when it has one, which
+     * takes the name as written and knows no namespace, else the specification (`getSpecByTagName`) of the
+     * name in its namespace. {@link MLElement.tagNameKind} and the guard of {@link MLElement.pretending}
+     * read it, so that a type selector and a pretender agree on what a tag is.
+     *
+     * Rules keyed on the specification (deprecated / obsolete elements) do not read it. Nor does the
+     * element that a pretender stands for (`as`): the name is the element itself there, not a tag to resolve,
+     * so it is judged by the specification and never passes through this method.
+     *
+     * @param localName - The name of the tag as the author wrote it, never the `as` of a pretender
+     * @param namespaceURI - The namespace of the element; not read when the parser has a rule, as Vue's is the same for every namespace
+     * @returns Whether the document takes the tag for a native element
+     */
+    isNativeTag(localName, namespaceURI) {
+        if (this.#isNativeTagRule) {
+            return this.#isNativeTagRule(localName);
+        }
+        return getSpecByTagName(this.specs.specs, localName, namespaceURI) != null;
+    }
+    /**
+     * Whether attribute names are JavaScript identifiers in the source language (JSX props such as
+     * `onClick`), which the `case-sensitive-attr-name` rule does not ask to be lower case.
+     *
+     * It says nothing about whether two spellings of a name are one attribute: that is up to how the
+     * name gets into the DOM ({@link MLDocument.attrNameRoute}) and to the element, and is decided by
+     * {@link MLAttr.nameKey}. Svelte and Astro tell the case of a tag name apart but not of an
+     * attribute name, and Vue sets its attributes through the DOM API though a template is still
+     * checked for the case of a name.
+     */
+    attrNameCaseSensitive;
+    /**
+     * How the name of an attribute gets into the DOM of the browser (`MLParser#attrNameRoute`, see
+     * `AttrNameRoute`). It decides whether `VIEWBOX` and `viewBox` are one attribute, which is a matter of the
+     * DOM and so of the element and the attribute as well; this is what the parser says about its language.
+     * `"html-parser"` when the parser does not say.
+     */
+    attrNameRoute;
     /**
      * Common settings applied globally to all rules, such as the ARIA version.
      * Rules use this as a fallback when their own options do not specify a value.
@@ -95,6 +148,11 @@ export class MLDocument extends MLParentNode {
         this.endTag = options?.endTag ?? 'omittable';
         this.#filename = options?.filename;
         this.tagNameCaseSensitive = options?.tagNameCaseSensitive ?? false;
+        this.componentNameVariants = options?.componentNameVariants ?? false;
+        this.isComponentName = options?.isComponentName ?? isComponentName;
+        this.#isNativeTagRule = options?.isNativeTag;
+        this.attrNameCaseSensitive = options?.attrNameCaseSensitive ?? false;
+        this.attrNameRoute = options?.attrNameRoute ?? 'html-parser';
         this.ruleCommonSettings = ruleCommonSettings;
         // Build UUID → AST node map for cross-reference lookups (e.g., pairNodeUuid)
         this.#astNodeMap = new Map(ast.nodeList.map(n => [n.uuid, n]));
@@ -2351,7 +2409,10 @@ export class MLDocument extends MLParentNode {
         }
     }
     #ruleMapping(ruleset) {
-        if (docLog.enabled) {
+        // Read once: the per-node loop below would otherwise hit the `enabled` getter for every node.
+        const docEnabled = docLog.enabled;
+        const ruleEnabled = ruleLog.enabled;
+        if (docEnabled) {
             docLog('Rule Mapping: %O', Object.keys(ruleset.rules));
         }
         const ruleMapper = new RuleMapper(this);
@@ -2369,7 +2430,7 @@ export class MLDocument extends MLParentNode {
         }
         // add rules to node
         for (const node of this.nodeList) {
-            if (docLog.enabled) {
+            if (docEnabled) {
                 docLog('Add rules to node <%s>', node.nodeName);
             }
             // global rules to each element
@@ -2401,7 +2462,7 @@ export class MLDocument extends MLParentNode {
                 if (!matches.matched) {
                     continue;
                 }
-                if (docLog.enabled) {
+                if (docEnabled) {
                     docLog('Matched nodeRule: <%s>(%s)', node.nodeName, matches.selector || '*');
                 }
                 const ruleList = Object.keys(nodeRule.rules);
@@ -2434,7 +2495,9 @@ export class MLDocument extends MLParentNode {
                     }
                     const globalRule = ruleset.rules[ruleName];
                     const mergedRule = globalRule == null ? convertedRule : mergeRule(globalRule, convertedRule);
-                    ruleLog('↑ nodeRule (%s): %O', ruleName, mergedRule);
+                    if (ruleEnabled) {
+                        ruleLog('↑ nodeRule (%s): %O', ruleName, mergedRule);
+                    }
                     ruleMapper.set(node, ruleName, {
                         from: 'nodeRules',
                         specificity: matches.specificity,
@@ -2497,7 +2560,7 @@ export class MLDocument extends MLParentNode {
                     if (!matches.matched) {
                         continue;
                     }
-                    if (docLog.enabled) {
+                    if (docEnabled) {
                         docLog('Matched childNodeRule: <%s>(%s), inheritance: %o', selectorTarget.nodeName, matches.selector || '*', !!nodeRule.inheritance);
                     }
                     const targetDescendants = nodeRule.inheritance ? descendants : children;
@@ -2532,7 +2595,9 @@ export class MLDocument extends MLParentNode {
                         }
                         const globalRule = ruleset.rules[ruleName];
                         const mergedRule = globalRule == null ? convertedRule : mergeRule(globalRule, convertedRule);
-                        ruleLog('↑ childNodeRule (%s): %O', ruleName, mergedRule);
+                        if (ruleEnabled) {
+                            ruleLog('↑ childNodeRule (%s): %O', ruleName, mergedRule);
+                        }
                         for (const descendant of targetDescendants) {
                             ruleMapper.set(descendant, ruleName, {
                                 from: 'childNodeRules',

package/lib/ml-dom/node/element.d.ts

@@ -36,16 +36,108 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
     readonly elementType: ElementType;
     /**
      * Whether this element belongs to a non-HTML namespace (e.g., SVG or MathML).
+     *
+     * Unlike {@link namespaceURI}, it does not follow the pretender: it says how the tag
+     * written here is parsed (whether the case of its name is kept, whether `/>` closes
+     * it), and the tag of a component is not parsed as the element it renders. An element
+     * given to a component as a child is, as it ends up inside what the component renders.
+     */
+    get isForeignElement(): boolean;
+    /**
+     * Whether two names would be one attribute on this element, for names that no attribute of the
+     * element stands behind (the names of a spec, of an option or of a rule value, where the
+     * attribute may be missing). It is {@link MLAttr.isNamedBy} without an attribute.
+     *
+     * The HTML syntax folds the ASCII case. A name that code sets through the DOM API is folded
+     * only on an element of the HTML namespace: on an SVG or MathML element it keeps its spelling,
+     * and a name with a capital letter is a prop of the framework. The props of a component are
+     * not folded, except that Vue camelizes them.
+     *
+     * With no attribute, whether the name is set through the DOM API is up to the parser alone: the
+     * attribute is not dynamic, so Svelte's name is read as the HTML parser reads it.
+     *
+     * @see https://dom.spec.whatwg.org/#dom-element-setattribute
+     * @see https://html.spec.whatwg.org/multipage/parsing.html#attribute-name-state
+     *
+     * @param a - A name
+     * @param b - The other name
+     * @returns `true` if both names are one attribute on this element
      */
-    readonly isForeignElement: boolean;
+    isSameAttrName(a: string, b: string): boolean;
+    /**
+     * Whether the `#custom` entry of a content model category (`:model(flow)` etc.) covers this element.
+     *
+     * Anything that is not a native HTML element counts, an authored component (`<Foo />`)
+     * as well as an autonomous custom element (`<x-foo>`). Keep it in step with `isTreatedAsCustom`
+     * of `permitted-contents` (`'pretended'` mode), which applies the same criterion to `#custom`;
+     * they are separate on purpose, as `isTreatedAsCustom` also serves the `'origin'` mode.
+     *
+     * Like {@link localName}, it follows the pretender, since a selector sees the element
+     * the component renders. A pretender target is created with `elementType: 'html'`, so it
+     * is a custom element when its own name has a hyphen. A target whose name is a component
+     * (`Tabs.Root`; the rule is the parser's, see {@link MLDocument.isComponentName}) is created as
+     * `'authored'` and counts like one written directly: the scanners of `pretenders.auto` end a chain at such a name when
+     * they cannot resolve it, and what that component renders is not known.
+     *
+     * Known limitation: the hyphen test is only the hyphen. A pretender target named after a reserved
+     * hyphenated name (`annotation-xml`, `font-face`, ...) counts as custom here, whereas the same
+     * element written directly does not. `isTreatedAsCustom` shares the limitation.
+     */
+    get isCustomElement(): boolean;
+    /**
+     * Whether the document tells the case of a tag name apart (see {@link MLDocument.tagNameCaseSensitive}).
+     * A type selector reads it, as {@link localName} alone cannot tell it: an element that HTML names
+     * case-insensitively (`<foobar>`) has a lowercase-folded pair of `localName` / `nodeName` in
+     * every document, but in JSX it is not `<FooBar>`.
+     *
+     * @implements `SelectorElement#tagNameCaseSensitive` of `@markuplint/selector`
+     */
+    get tagNameCaseSensitive(): boolean;
+    /**
+     * What this element is for a type selector, in a document that resolves a component by any
+     * spelling of its name (Vue, see {@link MLDocument.componentNameVariants}); `undefined` in any other.
+     *
+     * - `component`: not an HTML element (`<FooBar>`, `<foo-bar>`), which {@link localName} names as written
+     * - `native`: an HTML element that the document takes for native (`<button>`, see {@link MLDocument.isNativeTag}:
+     *   the parser's rule, as Vue's `isNativeTag`, else the specification), the guard of {@link pretending}.
+     *   The element that a pretender stands for is judged by the specification alone
+     * - `unknown-html`: an HTML element that it does not (`<foobar>`; in Vue also `<marquee>`, which has a
+     *   specification but resolves to a component when one is imported)
+     *
+     * Like {@link localName}, it follows the pretender, since a selector sees the element the component
+     * renders. An element of the SVG or MathML namespace has none: it keeps the case of its name.
+     *
+     * @implements `SelectorElement#tagNameKind` of `@markuplint/selector`
+     */
+    get tagNameKind(): 'component' | 'native' | 'unknown-html' | undefined;
+    /**
+     * Whether a name that a user writes for an element (the `tag` of a rule option, as against the
+     * type name of a selector, which {@link matches} takes) stands for this element, written as it is,
+     * in a document that resolves a component by any spelling of its name (Vue, see
+     * {@link MLDocument.componentNameVariants}): `FooBar` stands for `<foo-bar>` and `<fooBar>`.
+     *
+     * It is `false` in any other document, so that a caller that compares a name as it is can ask
+     * it as well without changing what it does there. It ignores the pretender: the name is the one
+     * the element is written with. To ask so, it hides the pretender of this element for the length of the
+     * call (as {@link matchMLSelector} does for its second try), so nothing in it may be async.
+     *
+     * @param name - The name as the user wrote it
+     * @returns Whether the name stands for this element
+     */
+    matchesTagNameVariant(name: string): boolean;
     /**
      * Whether this element was implicitly created (e.g., an omitted `<body>` tag in HTML).
      */
     readonly isOmitted: boolean;
     /**
      * The namespace URI of this element (e.g., `http://www.w3.org/1999/xhtml` for HTML elements).
+     *
+     * Like {@link localName}, it follows the pretender, so that a namespaced selector
+     * (`svg|svg`) and a spec lookup see the element the component renders. An element
+     * given to a component as a child takes the namespace of where the component renders
+     * it, resolved when the document pretends.
      */
-    readonly namespaceURI: NamespaceURI;
+    get namespaceURI(): NamespaceURI;
     readonly ontouchcancel?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
     readonly ontouchend?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
     readonly ontouchmove?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
@@ -524,6 +616,11 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      */
     get attributeStyleMap(): StylePropertyMap;
     /**
+     * Every attribute written on the tag, the second of two spellings of one name too: unlike a DOM
+     * element, which keeps one of them, a rule checks each attribute that the author wrote, and
+     * `no-duplicate-attr` reports the second. Which of them the DOM keeps is what {@link getAttribute}
+     * returns.
+     *
      * @implements DOM API: `Element`
      * @see https://dom.spec.whatwg.org/#dom-element-attributes
      */
@@ -1880,6 +1977,10 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      */
     getAnimations(options?: GetAnimationsOptions): Animation[];
     /**
+     * Whether `attrName` is the name of an attribute of this element is what {@link MLAttr.isNamedBy}
+     * says: `ROLE` is `role` on a `<div>` and, in JSX, is not on an `<svg>`. `hasAttribute`,
+     * `getAttributeToken`, `getAttributePretended`, a pretender's `fromAttr` and `getNamedItem` ask the same.
+     *
      * @implements DOM API: `Element`
      * @see https://dom.spec.whatwg.org/#ref-for-dom-element-getattribute%E2%91%A0
      */
@@ -1919,7 +2020,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * the original component element, not on the virtual pretender element.
      *
      * @implements `@markuplint/ml-core` API: `MLElement`
-     * @param attrName - The attribute name to look up (case-insensitive)
+     * @param attrName - The attribute name to look up (see {@link MLAttr.isNamedBy} for how its case is compared)
      * @returns The attribute value, or null if the attribute is not found
      */
     getAttributePretended(attrName: string): string | null;
@@ -1928,7 +2029,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * Unlike `getAttribute`, this returns the full `MLAttr` token objects.
      *
      * @implements `@markuplint/ml-core` API: `MLElement`
-     * @param attrName - The attribute name to look up (case-insensitive)
+     * @param attrName - The attribute name to look up (see {@link MLAttr.isNamedBy} for how its case is compared)
      * @returns An array of matching attribute tokens
      */
     getAttributeToken(attrName: string): MLAttr<T, O>[];