@markuplint/ml-core 5.2.0 → 5.3.0

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

@@ -43,6 +43,88 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * 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
+     */
+    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).
      */
@@ -534,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
      */
@@ -1890,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
      */
@@ -1929,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;
@@ -1938,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>[];