@markuplint/ml-core 5.4.0 → 5.6.0

package/lib/ml-dom/helper/tree-scope.js

@@ -0,0 +1,341 @@
+import { isPotentialCustomElementName } from '@markuplint/parser-utils';
+import { decodeEntities } from '@markuplint/shared';
+/**
+ * @module
+ *
+ * The tree of a node is what its `getRootNode()` returns: the document, the content of an
+ * HTML `template` element, or a declarative shadow root. An id is unique in a tree, and an id
+ * reference is resolved in a tree, as the specification says of "the element's tree".
+ *
+ * markuplint keeps the content of a `template` element as the children of the element (the
+ * syntax tree has no other place for it), so the boundary is made here and not by the shape of
+ * the tree: the queries of `MLParentNode`, `getRootNode()`, `treeParentElement`, the selector
+ * engine and `contains()` stop at it. `parentNode` / `parentElement` do not: the content
+ * model of a `template` element is validated against the elements that the syntax tree puts
+ * in it, so they go on to the `template` element. The algorithms of `@markuplint/ml-spec` walk up
+ * with `getTreeParentElement` / `getComposedParentElement`, which read `getRootNode()`, so the
+ * boundary made here is the boundary they stop at.
+ *
+ * @see https://dom.spec.whatwg.org/#concept-tree
+ * @see https://html.spec.whatwg.org/multipage/dom.html#the-id-attribute
+ * @see https://html.spec.whatwg.org/multipage/scripting.html#the-template-element
+ */
+export const HTML_NAMESPACE = 'http://www.w3.org/1999/xhtml';
+/**
+ * The names that the DOM accepts as a shadow host, besides a valid custom element name.
+ *
+ * @see https://dom.spec.whatwg.org/#valid-shadow-host-name
+ */
+const SHADOW_HOST_NAMES = new Set([
+    'article',
+    'aside',
+    'blockquote',
+    'body',
+    'div',
+    'footer',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'header',
+    'main',
+    'nav',
+    'p',
+    'section',
+    'span',
+]);
+/**
+ * Whether `node` is skipped when the parent of a `template` element is looked for: what the
+ * template engine or the framework renders away (a block of a template language, a fragment of
+ * JSX, a `template` with a directive such as `v-if`) leaves its children to the next element
+ * above.
+ *
+ * `isRenderedAway` of `@markuplint/rules` (`src/helpers.ts`) decides the same of an element for the
+ * rules that walk up the ancestors: a kind added here belongs to it too.
+ *
+ * @param node - A node of the syntax tree
+ * @returns `true` if the node is not an element of the output
+ */
+export function isTransparent(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+node) {
+    if (node.is(node.MARKUPLINT_PREPROCESSOR_BLOCK)) {
+        return true;
+    }
+    if (node.isFragment) {
+        return true;
+    }
+    return node.is(node.ELEMENT_NODE) && hasDirectiveTemplate(node);
+}
+/**
+ * Whether the element is a `template` that has a directive of a template engine (Vue's `v-if`,
+ * `v-for`, `v-slot`). The engine renders its children in place of it and drops it, so it is not
+ * an HTML `template` element.
+ *
+ * @param el - An element
+ * @returns `true` if it is such a `template`
+ */
+function hasDirectiveTemplate(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el) {
+    if (el.localName !== 'template') {
+        return false;
+    }
+    for (const attr of el.attributes) {
+        // A spread attribute (`{...props}`) sets attributes of the element, which stays
+        if (attr.isDirective && attr.localName !== '#spread') {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Whether the element is an HTML `template` element, which holds its children in `content`, a tree
+ * of its own.
+ *
+ * It is not when the element is a fragment, has a directive of a template engine, or the
+ * framework puts the children in the element itself (`templateContent: 'in-place'` of the spec).
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param el - An element
+ * @returns `true` if the children of the element belong to a tree of their own
+ */
+export function isHTMLTemplateElement(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el) {
+    if (el.isFragment || el.localName !== 'template' || el.namespaceURI !== HTML_NAMESPACE) {
+        return false;
+    }
+    if (el.ownerMLDocument.specs.templateContent === 'in-place') {
+        return false;
+    }
+    return !hasDirectiveTemplate(el);
+}
+/**
+ * The state of the `shadowrootmode` attribute of an HTML `template` element.
+ *
+ * @param template - A `template` element
+ * @returns `open` or `closed`, `none` for a missing or invalid value (the missing value default and
+ *   the invalid value default are both the None state), and `dynamic` for a value that is not known
+ *   until the template is rendered
+ * @see https://html.spec.whatwg.org/multipage/scripting.html#attr-template-shadowrootmode
+ */
+function getShadowRootModeState(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+template) {
+    const attr = template.getAttributeNode('shadowrootmode');
+    if (!attr || attr.isAbsent) {
+        return 'none';
+    }
+    if (attr.isDynamicValue) {
+        return 'dynamic';
+    }
+    const value = attr.value.toLowerCase();
+    return value === 'open' || value === 'closed' ? value : 'none';
+}
+/**
+ * The mode of the declarative shadow root that a `template` element asks for.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param template - An element
+ * @returns `open` or `closed`, or `null` when it is not an HTML `template` element, the
+ *   attribute is missing or invalid, or its value is dynamic
+ */
+export function getDeclarativeShadowRootMode(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+template) {
+    if (!isHTMLTemplateElement(template)) {
+        return null;
+    }
+    const state = getShadowRootModeState(template);
+    return state === 'open' || state === 'closed' ? state : null;
+}
+/**
+ * The element that the HTML parser makes the shadow host of a `template` element: its parent in
+ * the output, where what the engine renders away (see {@link isTransparent}) is skipped. It is the
+ * parent in the output of any node, so it is the host a light child is a child of.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param template - A `template` element, or any node whose parent in the output is wanted
+ * @returns The element, or `null` when the file has none above the node
+ */
+export function getShadowHost(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+template) {
+    let node = template.syntacticalParentNode;
+    while (node) {
+        if (node.is(node.DOCUMENT_NODE) || node.is(node.DOCUMENT_FRAGMENT_NODE)) {
+            return null;
+        }
+        if (!isTransparent(node) && node.is(node.ELEMENT_NODE)) {
+            return node;
+        }
+        node = node.syntacticalParentNode;
+    }
+    return null;
+}
+/**
+ * Whether the host can have a shadow root, judged by what the markup says.
+ *
+ * @param host - The parent element of a `template` element
+ * @returns `true` or `false`, and `null` for an element that is not what it is written as (a
+ *   component whose output is not known)
+ * @see https://dom.spec.whatwg.org/#concept-attach-a-shadow-root
+ */
+function canBeShadowHost(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+host) {
+    if (host.elementType === 'authored' && host.pretenderContext?.type !== 'pretender') {
+        return null;
+    }
+    if (host.namespaceURI !== HTML_NAMESPACE) {
+        return false;
+    }
+    const name = host.localName;
+    return SHADOW_HOST_NAMES.has(name) || isPotentialCustomElementName(name);
+}
+/**
+ * Whether the children written in `host` are its children in the output, so that a `template`
+ * among them is parsed in it. A pretended component renders them in the element it pretends to
+ * be only when it neither drops them (`slots: null`) nor puts them in a slot wrapper; a custom
+ * element keeps them in its light DOM. This is the same placement as the rendered parent
+ * `MLElement` gives a child for its namespace.
+ *
+ * @param host - The parent element of a `template` element
+ * @returns `false` when the component places the children elsewhere or not at all
+ */
+function rendersChildrenInItself(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+host) {
+    const context = host.pretenderContext;
+    if (context?.type !== 'pretender' || host.elementType === 'web-component') {
+        return true;
+    }
+    if (context.as.childNodes.length === 0) {
+        return false;
+    }
+    return !context.slotContent || context.slotContent.wrapper === context.as;
+}
+/**
+ * The `template` elements that sit in the output under the host, in the order of the markup,
+ * seen through what the engine renders away.
+ *
+ * @param host - A shadow host candidate
+ * @returns The `template` elements, which are HTML ones
+ */
+function getTemplatesOfHost(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+host) {
+    const templates = [];
+    for (const child of host.getPureChildNodes()) {
+        if (isTransparent(child)) {
+            templates.push(...getTemplatesOfHost(child));
+            continue;
+        }
+        if (child.is(child.ELEMENT_NODE) && isHTMLTemplateElement(child)) {
+            templates.push(child);
+        }
+    }
+    return templates;
+}
+/**
+ * Whether a declarative shadow root is attached to the parent of a `template` element, by what
+ * the HTML parser does with the start tag of `template` and what the DOM does to attach a shadow
+ * root: the mode is `open` or `closed` (ASCII case-insensitive), the parent is an HTML element with
+ * a valid shadow host name (a valid custom element name, or one of the names the DOM lists), and no
+ * earlier `template` of the same parent has attached one.
+ *
+ * The file is taken as parsed as a document that was served, so declarative shadow roots are
+ * allowed. The parser would not attach one to the top level of a fragment parsed through `innerHTML`,
+ * but whether a file is that is not something its markup says.
+ *
+ * Known limitation: a custom element definition may disable the shadow root (`disable shadow`),
+ * which only the script that defines the element tells. It is taken as not disabled.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param template - An element
+ * @returns The state. An element that is not an HTML `template` element is `not-attached`
+ * @see https://html.spec.whatwg.org/multipage/parsing.html#parsing-main-inhead
+ * @see https://dom.spec.whatwg.org/#concept-attach-a-shadow-root
+ */
+export function getDeclarativeShadowRootAttachment(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+template) {
+    if (!isHTMLTemplateElement(template)) {
+        return 'not-attached';
+    }
+    const mode = getShadowRootModeState(template);
+    if (mode === 'none') {
+        return 'not-attached';
+    }
+    const host = getShadowHost(template);
+    if (!host || !rendersChildrenInItself(host)) {
+        return 'unknown';
+    }
+    const hostCheck = canBeShadowHost(host);
+    if (hostCheck === false) {
+        return 'not-attached';
+    }
+    if (hostCheck === null || mode === 'dynamic') {
+        return 'unknown';
+    }
+    // The first `template` that asks for a shadow root and can have one takes the host.
+    let undecided = false;
+    for (const earlier of getTemplatesOfHost(host)) {
+        if (earlier === template) {
+            break;
+        }
+        const earlierMode = getShadowRootModeState(earlier);
+        if (earlierMode === 'none') {
+            continue;
+        }
+        if (earlierMode === 'dynamic') {
+            undecided = true;
+            continue;
+        }
+        return 'not-attached';
+    }
+    return undecided ? 'unknown' : 'attached';
+}
+/**
+ * The `template` element of a host whose declarative shadow root is attached, if there is one.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param host - An element
+ * @returns The `template` element whose content is the shadow root of the host, or `null`
+ */
+export function getShadowRootTemplate(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+host) {
+    return (getTemplatesOfHost(host).find(template => getDeclarativeShadowRootAttachment(template) === 'attached') ?? null);
+}
+/**
+ * The string that the DOM has for an attribute: the value with the character references in the markup
+ * resolved, so that `ab` is `ab`. A value that is written as code is a string already, with no
+ * character reference in it.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param attr - An attribute, or `null` for one that is missing
+ * @param value - A part of the value of the attribute as it is written (one token of a list), which the
+ *   attribute decides on whether it has a character reference; the whole value by default
+ * @returns The string, or `null` when the attribute is missing, a directive, or its value is not known
+ *   until it is rendered (a dynamic value)
+ * @see https://html.spec.whatwg.org/multipage/dom.html#the-id-attribute
+ */
+export function getDOMValue(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+attr, value) {
+    if (!attr || attr.isDynamicValue || attr.isDirective) {
+        return null;
+    }
+    const written = value ?? attr.value;
+    return attr.isExpressionValue ? written : decodeEntities(written);
+}

package/lib/ml-dom/helper/walkers.d.ts

@@ -3,4 +3,19 @@ import type { PlainData, RuleConfigValue } from '@markuplint/ml-config';
 export type Walker<T extends RuleConfigValue, O extends PlainData = undefined, N = MLNode<T, O>> = (node: N) => void | Promise<void> | Promise<void>[];
 export type SyncWalker<T extends RuleConfigValue, O extends PlainData = undefined, N = MLNode<T, O>> = (node: N) => void;
 export declare function syncWalk<T extends RuleConfigValue, O extends PlainData = undefined>(nodeList: ReadonlyArray<MLNode<T, O>>, walker: SyncWalker<T, O>): void;
+/**
+ * Walks the nodes in tree order (a node before its descendants), within one tree.
+ *
+ * Within one tree means it does not go into the children of an HTML `template` element, which
+ * are a tree of their own (see `tree-scope.ts`), and it does not report a `template` element that is
+ * in no tree (a declarative shadow root is attached to its parent, or whether it is cannot be told).
+ * With `across`, it goes into every tree and reports every node, in the order of the markup.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param nodeList - The nodes to start with: the children of the root of the tree
+ * @param walker - Called with each node
+ * @param across - Whether to go into the trees that other trees hold
+ */
+export declare function walkTree<T extends RuleConfigValue, O extends PlainData = undefined>(nodeList: ReadonlyArray<MLNode<T, O>>, walker: SyncWalker<T, O>, across?: boolean): void;
 export declare function sequentialWalker<T extends RuleConfigValue, O extends PlainData = undefined, N = MLNode<T, O>>(list: ReadonlyArray<N>, walker: Walker<T, O, N>): Promise<void>;

package/lib/ml-dom/helper/walkers.js

@@ -8,6 +8,40 @@ nodeList, walker) {
         walker(node);
     }
 }
+/**
+ * Walks the nodes in tree order (a node before its descendants), within one tree.
+ *
+ * Within one tree means it does not go into the children of an HTML `template` element, which
+ * are a tree of their own (see `tree-scope.ts`), and it does not report a `template` element that is
+ * in no tree (a declarative shadow root is attached to its parent, or whether it is cannot be told).
+ * With `across`, it goes into every tree and reports every node, in the order of the markup.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param nodeList - The nodes to start with: the children of the root of the tree
+ * @param walker - Called with each node
+ * @param across - Whether to go into the trees that other trees hold
+ */
+export function walkTree(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+nodeList, walker, across = false) {
+    for (const node of nodeList) {
+        if (node.is(node.ELEMENT_NODE)) {
+            const holdsOtherTree = node.isHTMLTemplateElement;
+            if (across || !node.isInNoTree) {
+                walker(node);
+            }
+            if (across || !holdsOtherTree) {
+                walkTree([...node.childNodes], walker, across);
+            }
+            continue;
+        }
+        walker(node);
+        if (node.is(node.MARKUPLINT_PREPROCESSOR_BLOCK)) {
+            walkTree([...node.childNodes], walker, across);
+        }
+    }
+}
 export function sequentialWalker(list, walker) {
     if (list.length === 0) {
         return Promise.resolve();

package/lib/ml-dom/index.d.ts

@@ -6,4 +6,8 @@ export type { MLDocumentType as DocumentType } from './node/document-type.js';
 export type { MLElement as Element } from './node/element.js';
 export type { MLText as Text } from './node/text.js';
 export type { MLChildNode as ChildNode } from './node/child-node.js';
+export type { MLShadowRoot as ShadowRoot } from './node/shadow-root.js';
+export type { DeclarativeShadowRootAttachment } from './helper/tree-scope.js';
+export { getDOMValue } from './helper/tree-scope.js';
+export { getRenderedChildNodes } from './helper/accname.js';
 export { MLDocument as Document } from './node/document.js';

package/lib/ml-dom/index.js

@@ -1 +1,3 @@
+export { getDOMValue } from './helper/tree-scope.js';
+export { getRenderedChildNodes } from './helper/accname.js';
 export { MLDocument as Document } from './node/document.js';

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

@@ -2,6 +2,7 @@ import type { MLElement } from './element.js';
 import type { AttributeNodeType } from './types.js';
 import type { MLASTAttr } from '@markuplint/ml-ast';
 import type { PlainData, RuleConfigValue } from '@markuplint/ml-config';
+import type { LiteralExpression } from '@markuplint/parser-utils';
 import { MLToken } from '../token/token.js';
 import { MLDomTokenList } from './dom-token-list.js';
 import { MLNode } from './node.js';
@@ -37,9 +38,13 @@ export declare class MLAttr<T extends RuleConfigValue, O extends PlainData = und
      */
     readonly isDuplicatable: boolean;
     /**
-     * Whether this attribute has a dynamic value (e.g., a template expression rather than a static string).
+     * Whether the value of this attribute is written as code (`{x}` of JSX, `:x="…"` of Vue, a value of
+     * `=` in Pug, a masked block of a template language), whatever the code is: a literal (`{true}`) or not
+     * (`{cond}`). It is a matter of syntax, which a rule that checks how the value is written reads
+     * (`attr-value-quotes`, `no-unescaped-char`), while {@link MLAttr.isDynamicValue} is a matter of the
+     * value that results.
      */
-    readonly isDynamicValue?: true;
+    readonly isExpressionValue?: true;
     /**
      * The token representing the attribute name, or null for spread attributes.
      */
@@ -69,13 +74,6 @@ export declare class MLAttr<T extends RuleConfigValue, O extends PlainData = und
      * The token representing the attribute value, or null if the attribute has no value.
      */
     readonly valueNode: MLToken | null;
-    /**
-     * Returns the "string" if HTML syntax. Otherwise, returns a type in its syntax.
-     *
-     * @default "string"
-     * @implements `@markuplint/ml-core` API: `MLAttr`
-     */
-    readonly valueType: 'string' | 'number' | 'boolean' | 'code';
     /**
      * Creates a new MLAttr instance from an AST attribute token.
      *
@@ -83,6 +81,66 @@ export declare class MLAttr<T extends RuleConfigValue, O extends PlainData = und
      * @param ownElement - The element that owns this attribute
      */
     constructor(astToken: MLASTAttr, ownElement: MLElement<T, O>);
+    /**
+     * Whether the framework does not output this attribute, which is known from its value being a literal
+     * that the framework drops (`disabled={false}`, `title={null}`). It is still in the list of the
+     * attributes of the element (`MLElement#attributes`), as a name that is misspelled is so whatever its
+     * value is, and a lookup by name (`getAttribute`, `hasAttribute`) does not find it, as the DOM does not.
+     * An absent attribute is {@link MLAttr.isDynamicValue} as well, so that a rule that reads the value skips it.
+     *
+     * Which rules skip it: a rule that judges the value or the presence of an attribute (the value of
+     * `aria-*`, a required attribute, a conflict between two attributes) reads what the framework outputs,
+     * and an attribute that is not output is not there to judge. A rule that judges the name (a misspelling,
+     * a deprecated or obsolete attribute, the order) judges what the author wrote, so it still reports an
+     * absent attribute.
+     */
+    get isAbsent(): true | undefined;
+    /**
+     * Whether the value of this attribute is not known: the code is not a literal (`{cond}`), the
+     * framework renders a literal in a way that is not known (`disabled={""}`), or the attribute is
+     * not output ({@link MLAttr.isAbsent}), where there is no value to read.
+     *
+     * It is not whether the value is written as code (that is {@link MLAttr.isExpressionValue}): a
+     * literal that is written as code (`aria-busy={true}`) is rendered by the framework to a value
+     * (`"true"`), which is known.
+     *
+     * A rule that reads it to skip a value that it cannot know reads this; a rule that asks how the
+     * value is written (its quotes, its escapes) reads {@link MLAttr.isExpressionValue} instead.
+     *
+     * On a component (`elementType: "authored"`) an attribute is a prop, which is rendered where it is
+     * forwarded to, not here: a literal in it is not dynamic, and its `value` is the string form of the
+     * literal ({@link MLAttr.literal}). What the component renders is not known, and that is told by
+     * `MLElement#hasMutableChildren`, not by the attributes of the component.
+     */
+    get isDynamicValue(): true | undefined;
+    /**
+     * Whether this attribute is made by a pretender (`pretenders` of a configuration): it is not in the
+     * source, so the position of its tokens is that of the element, and a fix of a violation on it
+     * would rewrite the tag.
+     *
+     * An attribute that a pretender takes over from the source (`inheritAttrs`) is not.
+     *
+     * A fix of a violation that is reported on a pretended attribute is dropped (`MLRule`), and a rule
+     * that fixes by the range of the attributes of an element (`attr-order`) leaves them out.
+     */
+    get isPretended(): boolean;
+    /**
+     * The literal that the value of this attribute is written as, when it is nothing but a literal in a
+     * language that can be read as one: `{true}`, `{"x"}`, `:x="0"`, or no value at all in the
+     * shorthand of JSX (`<div aria-hidden>` is `true`). `null` otherwise.
+     *
+     * What a literal is rendered as depends on the framework, the element and the attribute name
+     * ({@link MLAttr.value}, {@link MLAttr.isAbsent}); this is what is written.
+     */
+    get literal(): LiteralExpression | null;
+    /**
+     * Returns the "string" if HTML syntax. Otherwise, returns a type in its syntax. An attribute whose value
+     * is a literal that is resolved is "string", whichever language it is written in.
+     *
+     * @default "string"
+     * @implements `@markuplint/ml-core` API: `MLAttr`
+     */
+    get valueType(): 'string' | 'number' | 'boolean' | 'code';
     /**
      * Returns the local name portion of the attribute (without namespace prefix).
      *
@@ -152,7 +210,8 @@ export declare class MLAttr<T extends RuleConfigValue, O extends PlainData = und
      * 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.
+     * (Svelte), whether this one is written as code: how its name is set is a matter of how it is
+     * written, not of the value that results.
      */
     get isSetThroughDOMAPI(): boolean;
     /**
@@ -162,6 +221,14 @@ export declare class MLAttr<T extends RuleConfigValue, O extends PlainData = und
      * @implements `SelectorAttr#nameCaseInsensitive` of `@markuplint/selector`
      */
     get nameCaseInsensitive(): boolean;
+    /**
+     * Whether the framework does not output this attribute, so that no selector matches it
+     * ({@link MLAttr.isAbsent}). It is a boolean because `SelectorAttr#absent` of `@markuplint/selector`
+     * is the one that a selector reads.
+     *
+     * @implements `SelectorAttr#absent` of `@markuplint/selector`
+     */
+    get absent(): boolean;
     /**
      * The name that a selector is matched with.
      *