@markuplint/ml-core 5.4.0 → 5.6.0

package/lib/ml-dom/node/shadow-root.d.ts

@@ -0,0 +1,162 @@
+import type { MLDocument } from './document.js';
+import type { MLElement } from './element.js';
+import type { MLASTNode } from '@markuplint/ml-ast';
+import type { PlainData, RuleConfigValue } from '@markuplint/ml-config';
+import { MLDocumentFragment } from './document-fragment.js';
+/**
+ * A declarative shadow root: the content of a `template` element with a `shadowrootmode` attribute
+ * that the HTML parser attaches to the parent of the `template` element as a shadow root. As the
+ * parser sets the template contents of such a `template` element to the shadow root, a
+ * shadow root is the `content` of its `template` element, and it is a tree of its own.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @see https://html.spec.whatwg.org/multipage/parsing.html#parsing-main-inhead
+ */
+export declare class MLShadowRoot<T extends RuleConfigValue, O extends PlainData = undefined> extends MLDocumentFragment<T, O> implements ShadowRoot {
+    #private;
+    /**
+     * @param astNode - A copy of the AST node of the `template` element that has a uuid of its own
+     * @param document - The owning document
+     * @param template - The `template` element whose content it is
+     */
+    constructor(astNode: MLASTNode, document: MLDocument<T, O>, template: MLElement<T, O>);
+    /**
+     * The element that the shadow root is attached to.
+     *
+     * @see https://dom.spec.whatwg.org/#dom-shadowroot-host
+     */
+    get host(): MLElement<T, O>;
+    /**
+     * The `shadowrootmode` attribute of the `template` element.
+     *
+     * @see https://dom.spec.whatwg.org/#dom-shadowroot-mode
+     */
+    get mode(): 'open' | 'closed';
+    /**
+     * Whether the `template` element has the `shadowrootdelegatesfocus` attribute.
+     *
+     * @see https://dom.spec.whatwg.org/#dom-shadowroot-delegatesfocus
+     */
+    get delegatesFocus(): boolean;
+    /**
+     * Whether the `template` element has the `shadowrootclonable` attribute.
+     *
+     * @see https://dom.spec.whatwg.org/#dom-shadowroot-clonable
+     */
+    get clonable(): boolean;
+    /**
+     * Whether the `template` element has the `shadowrootserializable` attribute.
+     *
+     * @see https://dom.spec.whatwg.org/#dom-shadowroot-serializable
+     */
+    get serializable(): boolean;
+    /**
+     * `manual` when the `shadowrootslotassignment` attribute of the `template` element says so,
+     * `named` otherwise.
+     *
+     * @see https://dom.spec.whatwg.org/#dom-shadowroot-slotassignment
+     */
+    get slotAssignment(): 'named' | 'manual';
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `ShadowRoot`
+     */
+    get innerHTML(): string;
+    set innerHTML(html: string);
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `ShadowRoot`
+     */
+    get onslotchange(): ((this: ShadowRoot, ev: Event) => any) | null;
+    set onslotchange(handler: ((this: ShadowRoot, ev: Event) => any) | null);
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `ShadowRoot`
+     */
+    getHTML(options?: GetHTMLOptions): string;
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `ShadowRoot`
+     */
+    setHTMLUnsafe(html: string): void;
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    get activeElement(): Element | null;
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    get adoptedStyleSheets(): CSSStyleSheet[];
+    set adoptedStyleSheets(sheets: CSSStyleSheet[]);
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    get customElementRegistry(): CustomElementRegistry | null;
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    get fullscreenElement(): Element | null;
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    get pictureInPictureElement(): Element | null;
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    get pointerLockElement(): Element | null;
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    get styleSheets(): StyleSheetList;
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    elementFromPoint(x: number, y: number): Element | null;
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    elementsFromPoint(x: number, y: number): Element[];
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    getAnimations(): Animation[];
+}

package/lib/ml-dom/node/shadow-root.js

@@ -0,0 +1,219 @@
+import { getShadowHost } from '../helper/tree-scope.js';
+import { MLDocumentFragment } from './document-fragment.js';
+import { UnexpectedCallError } from '@markuplint/shared';
+/**
+ * A declarative shadow root: the content of a `template` element with a `shadowrootmode` attribute
+ * that the HTML parser attaches to the parent of the `template` element as a shadow root. As the
+ * parser sets the template contents of such a `template` element to the shadow root, a
+ * shadow root is the `content` of its `template` element, and it is a tree of its own.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @see https://html.spec.whatwg.org/multipage/parsing.html#parsing-main-inhead
+ */
+export class MLShadowRoot extends MLDocumentFragment {
+    #template;
+    /**
+     * @param astNode - A copy of the AST node of the `template` element that has a uuid of its own
+     * @param document - The owning document
+     * @param template - The `template` element whose content it is
+     */
+    constructor(astNode, 
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    document, 
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    template) {
+        super(astNode, document);
+        this.#template = template;
+    }
+    /**
+     * The element that the shadow root is attached to.
+     *
+     * @see https://dom.spec.whatwg.org/#dom-shadowroot-host
+     */
+    get host() {
+        const host = getShadowHost(this.#template);
+        if (!host) {
+            throw new TypeError('A shadow root is attached to an element');
+        }
+        return host;
+    }
+    /**
+     * The `shadowrootmode` attribute of the `template` element.
+     *
+     * @see https://dom.spec.whatwg.org/#dom-shadowroot-mode
+     */
+    get mode() {
+        return this.#template.declarativeShadowRootMode ?? 'open';
+    }
+    /**
+     * Whether the `template` element has the `shadowrootdelegatesfocus` attribute.
+     *
+     * @see https://dom.spec.whatwg.org/#dom-shadowroot-delegatesfocus
+     */
+    get delegatesFocus() {
+        return this.#template.hasAttribute('shadowrootdelegatesfocus');
+    }
+    /**
+     * Whether the `template` element has the `shadowrootclonable` attribute.
+     *
+     * @see https://dom.spec.whatwg.org/#dom-shadowroot-clonable
+     */
+    get clonable() {
+        return this.#template.hasAttribute('shadowrootclonable');
+    }
+    /**
+     * Whether the `template` element has the `shadowrootserializable` attribute.
+     *
+     * @see https://dom.spec.whatwg.org/#dom-shadowroot-serializable
+     */
+    get serializable() {
+        return this.#template.hasAttribute('shadowrootserializable');
+    }
+    /**
+     * `manual` when the `shadowrootslotassignment` attribute of the `template` element says so,
+     * `named` otherwise.
+     *
+     * @see https://dom.spec.whatwg.org/#dom-shadowroot-slotassignment
+     */
+    get slotAssignment() {
+        return this.#template.getAttribute('shadowrootslotassignment')?.toLowerCase() === 'manual' ? 'manual' : 'named';
+    }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `ShadowRoot`
+     */
+    get innerHTML() {
+        throw new UnexpectedCallError('Not supported "innerHTML" property');
+    }
+    set innerHTML(html) {
+        throw new UnexpectedCallError('Not supported "innerHTML" property');
+    }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `ShadowRoot`
+     */
+    get onslotchange() {
+        throw new UnexpectedCallError('Not supported "onslotchange" property');
+    }
+    set onslotchange(handler) {
+        throw new UnexpectedCallError('Not supported "onslotchange" property');
+    }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `ShadowRoot`
+     */
+    getHTML(
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    options) {
+        throw new UnexpectedCallError('Not supported "getHTML" method');
+    }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `ShadowRoot`
+     */
+    setHTMLUnsafe(html) {
+        throw new UnexpectedCallError('Not supported "setHTMLUnsafe" method');
+    }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    get activeElement() {
+        throw new UnexpectedCallError('Not supported "activeElement" property');
+    }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    get adoptedStyleSheets() {
+        throw new UnexpectedCallError('Not supported "adoptedStyleSheets" property');
+    }
+    set adoptedStyleSheets(sheets) {
+        throw new UnexpectedCallError('Not supported "adoptedStyleSheets" property');
+    }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    get customElementRegistry() {
+        throw new UnexpectedCallError('Not supported "customElementRegistry" property');
+    }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    get fullscreenElement() {
+        throw new UnexpectedCallError('Not supported "fullscreenElement" property');
+    }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    get pictureInPictureElement() {
+        throw new UnexpectedCallError('Not supported "pictureInPictureElement" property');
+    }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    get pointerLockElement() {
+        throw new UnexpectedCallError('Not supported "pointerLockElement" property');
+    }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    get styleSheets() {
+        throw new UnexpectedCallError('Not supported "styleSheets" property');
+    }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    elementFromPoint(x, y) {
+        throw new UnexpectedCallError('Not supported "elementFromPoint" method');
+    }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    elementsFromPoint(x, y) {
+        throw new UnexpectedCallError('Not supported "elementsFromPoint" method');
+    }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `DocumentOrShadowRoot`
+     */
+    getAnimations() {
+        throw new UnexpectedCallError('Not supported "getAnimations" method');
+    }
+}

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

@@ -1,3 +1,4 @@
+import type { MLElement } from './element.js';
 import type { TextNodeType } from './types.js';
 import type { MLASTText } from '@markuplint/ml-ast';
 import type { PlainData, RuleConfigValue } from '@markuplint/ml-config';
@@ -12,12 +13,20 @@ import { MLCharacterData } from './character-data.js';
  */
 export declare class MLText<T extends RuleConfigValue, O extends PlainData = undefined> extends MLCharacterData<T, O, MLASTText> implements Text {
     /**
-     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     * The slot of an open declarative shadow root that this text is assigned to, or `null` when no
+     * slot takes it, the root is closed (the DOM does not expose it), or the assignment is not known.
      *
-     * @unsupported
      * @implements DOM API: `Text`
+     * @see https://dom.spec.whatwg.org/#dom-slotable-assignedslot
+     */
+    get assignedSlot(): HTMLSlotElement | null;
+    /**
+     * The slot that places this text in the flat tree. See {@link MLElement.getFlatTreeSlot}.
+     *
+     * @implements `@markuplint/ml-core` API: `MLText`
+     * @see https://dom.spec.whatwg.org/#find-a-slot
      */
-    get assignedSlot(): HTMLSlotElement;
+    getFlatTreeSlot(): MLElement<T, O> | null | undefined;
     /**
      * Returns `true` if this text node originated from an invalid (bogus) AST
      * node, such as an orphaned end tag.

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

@@ -1,3 +1,4 @@
+import { getAssignedSlot, getFlatTreeSlot } from '../helper/slot-assignment.js';
 import { MLCharacterData } from './character-data.js';
 import { UnexpectedCallError } from '@markuplint/shared';
 /**
@@ -16,13 +17,23 @@ const rawTextElements = new Set(['script', 'style']);
  */
 export class MLText extends MLCharacterData {
     /**
-     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     * The slot of an open declarative shadow root that this text is assigned to, or `null` when no
+     * slot takes it, the root is closed (the DOM does not expose it), or the assignment is not known.
      *
-     * @unsupported
      * @implements DOM API: `Text`
+     * @see https://dom.spec.whatwg.org/#dom-slotable-assignedslot
      */
     get assignedSlot() {
-        throw new UnexpectedCallError('Not supported  "assignedSlot" property');
+        return getAssignedSlot(this);
+    }
+    /**
+     * The slot that places this text in the flat tree. See {@link MLElement.getFlatTreeSlot}.
+     *
+     * @implements `@markuplint/ml-core` API: `MLText`
+     * @see https://dom.spec.whatwg.org/#find-a-slot
+     */
+    getFlatTreeSlot() {
+        return getFlatTreeSlot(this);
     }
     /**
      * Returns `true` if this text node originated from an invalid (bogus) AST

package/lib/ml-rule/ml-rule.js

@@ -172,7 +172,10 @@ export class MLRule {
         const aliasName = this.baseRuleId ? this.name : undefined;
         const violations = context.reports.map(report => {
             let fixData;
-            if (fix && report.fix) {
+            // An attribute that a pretender made is not in the source: the position of its tokens is that of
+            // the element, so a fix that edits the range of the attribute would rewrite the tag
+            const isPretendedScope = 'scope' in report && 'isPretended' in report.scope && report.scope.isPretended;
+            if (fix && report.fix && !isPretendedScope) {
                 const edits = report.fix(sharedFixer);
                 const editArray = Array.isArray(edits) ? edits : [edits];
                 if (editArray.length > 0) {

package/lib/test/index.js

@@ -20,6 +20,9 @@ export function createTestDocument(sourceCode, options) {
         // The settings of the language are what the parser says, as `MLCore` hands them to the document
         endTag: usedParser.endTag,
         booleanish: usedParser.booleanish,
+        attrExpressionLanguage: usedParser.attrExpressionLanguage,
+        literalValues: usedParser.literalValues,
+        slotElement: usedParser.slotElement,
         tagNameCaseSensitive: usedParser.tagNameCaseSensitive,
         componentNameVariants: usedParser.componentNameVariants,
         isComponentName: usedParser.isComponentName?.bind(usedParser),

package/lib/utils/index.d.ts

@@ -1 +1,3 @@
 export { getLocationFromChars } from './get-location-from-chars.js';
+export type { LocatedNode, LocatedToken } from './search-node-at-location.js';
+export { searchNodeAtLocation } from './search-node-at-location.js';

package/lib/utils/index.js

@@ -1 +1,2 @@
 export { getLocationFromChars } from './get-location-from-chars.js';
+export { searchNodeAtLocation } from './search-node-at-location.js';

package/lib/utils/search-node-at-location.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A source range: from its start, included, to its end, excluded (the end is
+ * where the next token starts). Without an end, it holds only its start.
+ */
+export interface LocatedToken {
+    readonly startLine: number;
+    readonly startCol: number;
+    readonly endLine?: number;
+    readonly endCol?: number;
+}
+/**
+ * A node with its source range. The range of an element is its start tag; its
+ * end tag, which is not in a document's node list, is `closeTag`.
+ */
+export interface LocatedNode extends LocatedToken {
+    readonly closeTag?: LocatedToken | null;
+}
+/**
+ * Finds the node of `nodeList` at the source location `line`:`col` (both 1-based).
+ *
+ * The node is the one whose range holds the position, or whose end tag does: a
+ * document's node list has no attribute nodes and no end tags, so a position at
+ * an attribute, inside its value or in an end tag is the element that has it. Of
+ * several such nodes the last in the list is taken: the innermost. A block
+ * (`#ml-block`) holds the elements nested in it, and an omitted element
+ * (`<tbody>` with an empty source) starts where its first child does.
+ *
+ * The list is in document order, as the parser sorts its nodes by offset, so the
+ * search stops at the first node that starts after the position. It works on the
+ * structural `LocatedNode` so that it reads the node list of any version of the
+ * engine: the language server searches the document of the markuplint the user
+ * installed, and the suppressions search a node list cast to their own type.
+ *
+ * @param nodeList - The nodes of a document, in document order.
+ * @param line - The 1-based line number to search at.
+ * @param col - The 1-based column number to search at.
+ * @returns The node at the location, or `null` if there is none.
+ */
+export declare function searchNodeAtLocation<N extends LocatedNode>(nodeList: Iterable<N>, line: number, col: number): N | null;

package/lib/utils/search-node-at-location.js

@@ -0,0 +1,53 @@
+/**
+ * Finds the node of `nodeList` at the source location `line`:`col` (both 1-based).
+ *
+ * The node is the one whose range holds the position, or whose end tag does: a
+ * document's node list has no attribute nodes and no end tags, so a position at
+ * an attribute, inside its value or in an end tag is the element that has it. Of
+ * several such nodes the last in the list is taken: the innermost. A block
+ * (`#ml-block`) holds the elements nested in it, and an omitted element
+ * (`<tbody>` with an empty source) starts where its first child does.
+ *
+ * The list is in document order, as the parser sorts its nodes by offset, so the
+ * search stops at the first node that starts after the position. It works on the
+ * structural `LocatedNode` so that it reads the node list of any version of the
+ * engine: the language server searches the document of the markuplint the user
+ * installed, and the suppressions search a node list cast to their own type.
+ *
+ * @param nodeList - The nodes of a document, in document order.
+ * @param line - The 1-based line number to search at.
+ * @param col - The 1-based column number to search at.
+ * @returns The node at the location, or `null` if there is none.
+ */
+export function searchNodeAtLocation(nodeList, line, col) {
+    let found = null;
+    for (const node of nodeList) {
+        if (isBefore(line, col, node)) {
+            break;
+        }
+        if (holdsLocation(node, line, col) || (node.closeTag != null && holdsLocation(node.closeTag, line, col))) {
+            found = node;
+        }
+    }
+    return found;
+}
+/** Whether `line`:`col` comes before the start of `token`. */
+function isBefore(line, col, token) {
+    return line < token.startLine || (line === token.startLine && col < token.startCol);
+}
+/**
+ * Whether `line`:`col` is the start of `token` or in its range. The start is
+ * compared first: the end of an `MLNode` is computed from its source on every read.
+ */
+function holdsLocation(token, line, col) {
+    if (isBefore(line, col, token)) {
+        return false;
+    }
+    if (line === token.startLine && col === token.startCol) {
+        return true;
+    }
+    if (token.endLine === undefined || token.endCol === undefined) {
+        return false;
+    }
+    return line < token.endLine || (line === token.endLine && col < token.endCol);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/ml-core",
-	"version": "5.4.0",
+	"version": "5.6.0",
 	"description": "The core module of markuplint",
 	"repository": {
 		"type": "git",
@@ -22,9 +22,6 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"typedoc": {
-		"entryPoint": "./src/index.ts"
-	},
 	"scripts": {
 		"build": "tsc --project tsconfig.build.json",
 		"dev": "tsc --watch --project tsconfig.build.json",
@@ -34,20 +31,20 @@
 		"./lib/configs.js": "./lib/configs.browser.js"
 	},
 	"dependencies": {
-		"@markuplint/config-presets": "5.4.0",
-		"@markuplint/html-parser": "5.4.0",
-		"@markuplint/html-spec": "5.4.0",
-		"@markuplint/i18n": "5.3.0",
-		"@markuplint/ml-ast": "5.3.0",
-		"@markuplint/ml-config": "5.4.0",
-		"@markuplint/ml-spec": "5.4.0",
-		"@markuplint/parser-utils": "5.4.0",
-		"@markuplint/selector": "5.4.0",
-		"@markuplint/shared": "5.4.0",
+		"@markuplint/config-presets": "5.6.0",
+		"@markuplint/html-parser": "5.6.0",
+		"@markuplint/html-spec": "5.6.0",
+		"@markuplint/i18n": "5.6.0",
+		"@markuplint/ml-ast": "5.6.0",
+		"@markuplint/ml-config": "5.6.0",
+		"@markuplint/ml-spec": "5.6.0",
+		"@markuplint/parser-utils": "5.6.0",
+		"@markuplint/selector": "5.6.0",
+		"@markuplint/shared": "5.6.0",
 		"@types/debug": "^4.1.13",
 		"debug": "^4.4.3",
 		"is-plain-object": "^5.1.0",
 		"type-fest": "^5.10.0"
 	},
-	"gitHead": "647f6fb5d5743f060678599c97e9c84b58970747"
+	"gitHead": "eade3d7202682e567f3c1b6985478f1d4b5c5481"
 }