@markuplint/rules 4.11.2 → 5.0.0-alpha.0

package/lib/neighbor-popovers/index.js

@@ -1,14 +1,36 @@
 import { createRule } from '@markuplint/ml-core';
-import { mayBeFocusable } from '@markuplint/ml-spec';
+import { ARIA_RECOMMENDED_VERSION, mayBeFocusable } from '@markuplint/ml-spec';
 import meta from './meta.js';
-// TODO: It will be received from config
-const ARIA_VERSION = '1.2';
+/**
+ * Command values from the Invoker Commands API that relate to popover behavior.
+ * Comparison is case-insensitive per the HTML spec.
+ */
+const POPOVER_COMMANDS = new Set(['toggle-popover', 'show-popover', 'hide-popover']);
+/**
+ * Rule that detects perceptible content between a popover trigger and its target.
+ *
+ * When a `[popovertarget]` element or a `[commandfor]` element with a popover-related
+ * `command` attribute and its corresponding `[popover]` target exist in the DOM, any
+ * focusable elements, elements with accessible names, or non-whitespace text nodes
+ * between them are reported as violations.
+ */
 export default createRule({
     meta: meta,
     verify({ document, report, t }) {
-        const triggers = document.querySelectorAll('[popovertarget]');
+        const ariaVersion = document.ruleCommonSettings?.ariaVersion ?? ARIA_RECOMMENDED_VERSION;
+        const triggers = document.querySelectorAll('[popovertarget], [commandfor]');
         Triggers: for (const trigger of triggers) {
-            const targetId = trigger.getAttribute('popovertarget');
+            let targetId = null;
+            const popovertarget = trigger.getAttribute('popovertarget');
+            if (popovertarget) {
+                targetId = popovertarget;
+            }
+            else {
+                const command = trigger.getAttribute('command');
+                if (command && POPOVER_COMMANDS.has(command.toLowerCase())) {
+                    targetId = trigger.getAttribute('commandfor');
+                }
+            }
             if (!targetId) {
                 continue;
             }
@@ -26,7 +48,7 @@ export default createRule({
                 }
                 if ((node.is(node.ELEMENT_NODE) &&
                     // Element has accessible name
-                    (node.getAccessibleName(ARIA_VERSION) ||
+                    (node.getAccessibleName(ariaVersion) ||
                         // Element is focusable
                         mayBeFocusable(node, node.ownerMLDocument.specs))) ||
                     (node.is(node.TEXT_NODE) &&

package/lib/neighbor-popovers/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for the `neighbor-popovers` rule, categorized as accessibility. */
 declare const _default: {
     readonly category: "a11y";
 };

package/lib/neighbor-popovers/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for the `neighbor-popovers` rule, categorized as accessibility. */
 export default {
     category: 'a11y',
 };

package/lib/no-ambiguous-navigable-target-names/index.d.ts

@@ -1,2 +1,10 @@
+/**
+ * Rule that warns against ambiguous navigable target names.
+ *
+ * Detects attribute values (e.g., `target`) that look like browsing context
+ * keywords (such as `_blank`, `_self`) but are missing the leading underscore,
+ * which would make them navigable target names instead of keywords. Suggests
+ * adding the underscore prefix when applicable.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, undefined>>;
 export default _default;

package/lib/no-ambiguous-navigable-target-names/index.js

@@ -1,6 +1,14 @@
 import { createRule, getAttrSpecs } from '@markuplint/ml-core';
 import { valueCheck } from '../attr-check.js';
 import meta from './meta.js';
+/**
+ * Rule that warns against ambiguous navigable target names.
+ *
+ * Detects attribute values (e.g., `target`) that look like browsing context
+ * keywords (such as `_blank`, `_self`) but are missing the leading underscore,
+ * which would make them navigable target names instead of keywords. Suggests
+ * adding the underscore prefix when applicable.
+ */
 export default createRule({
     meta: meta,
     defaultSeverity: 'warning',

package/lib/no-ambiguous-navigable-target-names/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for the `no-ambiguous-navigable-target-names` rule, categorized as accessibility. */
 declare const _default: {
     readonly category: "a11y";
 };

package/lib/no-ambiguous-navigable-target-names/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for the `no-ambiguous-navigable-target-names` rule, categorized as accessibility. */
 export default {
     category: 'a11y',
 };

package/lib/no-boolean-attr-value/index.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Rule that disallows explicit values on boolean attributes.
+ *
+ * Checks each attribute against the HTML spec and reports when a boolean
+ * attribute (e.g., `disabled`, `checked`) is written with an explicit value
+ * such as `disabled="disabled"` instead of the bare attribute name.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<import("@markuplint/ml-core").RuleConfigValue, undefined>>;
 export default _default;

package/lib/no-boolean-attr-value/index.js

@@ -1,5 +1,12 @@
 import { createRule, getAttrSpecs } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that disallows explicit values on boolean attributes.
+ *
+ * Checks each attribute against the HTML spec and reports when a boolean
+ * attribute (e.g., `disabled`, `checked`) is written with an explicit value
+ * such as `disabled="disabled"` instead of the bare attribute name.
+ */
 export default createRule({
     meta: meta,
     defaultSeverity: 'warning',

package/lib/no-boolean-attr-value/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for `no-boolean-attr-value`: categorized as a style rule. */
 declare const _default: {
     readonly category: "style";
 };

package/lib/no-boolean-attr-value/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for `no-boolean-attr-value`: categorized as a style rule. */
 export default {
     category: 'style',
 };

package/lib/no-consecutive-br/index.d.ts

@@ -1,2 +1,10 @@
+/**
+ * Rule that disallows consecutive `<br>` elements.
+ *
+ * Queries all `<br>` elements in the document and checks whether the next
+ * non-whitespace sibling is another `<br>`. Consecutive line breaks are
+ * typically a sign that a more semantic element (e.g., `<p>`) should be
+ * used instead, which is important for accessibility.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<import("@markuplint/ml-core").RuleConfigValue, undefined>>;
 export default _default;

package/lib/no-consecutive-br/index.js

@@ -1,5 +1,13 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that disallows consecutive `<br>` elements.
+ *
+ * Queries all `<br>` elements in the document and checks whether the next
+ * non-whitespace sibling is another `<br>`. Consecutive line breaks are
+ * typically a sign that a more semantic element (e.g., `<p>`) should be
+ * used instead, which is important for accessibility.
+ */
 export default createRule({
     meta: meta,
     defaultSeverity: 'warning',

package/lib/no-consecutive-br/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for `no-consecutive-br`: categorized as an accessibility rule. */
 declare const _default: {
     readonly category: "a11y";
 };

package/lib/no-consecutive-br/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for `no-consecutive-br`: categorized as an accessibility rule. */
 export default {
     category: 'a11y',
 };

package/lib/no-default-value/index.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Rule that disallows explicitly setting an attribute to its default value.
+ *
+ * Looks up each attribute's default value from the spec and reports when
+ * the authored value matches the default, since the attribute can be
+ * omitted entirely for the same effect.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<import("@markuplint/ml-core").RuleConfigValue, undefined>>;
 export default _default;

package/lib/no-default-value/index.js

@@ -1,6 +1,13 @@
 import { createRule, getAttrSpecs } from '@markuplint/ml-core';
 import { toNormalizedValue } from '../helpers.js';
 import meta from './meta.js';
+/**
+ * Rule that disallows explicitly setting an attribute to its default value.
+ *
+ * Looks up each attribute's default value from the spec and reports when
+ * the authored value matches the default, since the attribute can be
+ * omitted entirely for the same effect.
+ */
 export default createRule({
     meta: meta,
     defaultSeverity: 'warning',

package/lib/no-default-value/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for `no-default-value`: categorized as a style rule. */
 declare const _default: {
     readonly category: "style";
 };

package/lib/no-default-value/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for `no-default-value`: categorized as a style rule. */
 export default {
     category: 'style',
 };

package/lib/no-duplicate-dt/index.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Rule that validates there are no duplicate `<dt>` elements within a `<dl>`.
+ *
+ * Iterates through each definition list and checks that no two `<dt>` elements
+ * (direct children or wrapped in `<div>`) share the same text content.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<import("@markuplint/ml-core").RuleConfigValue, undefined>>;
 export default _default;

package/lib/no-duplicate-dt/index.js

@@ -1,5 +1,11 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that validates there are no duplicate `<dt>` elements within a `<dl>`.
+ *
+ * Iterates through each definition list and checks that no two `<dt>` elements
+ * (direct children or wrapped in `<div>`) share the same text content.
+ */
 export default createRule({
     meta: meta,
     verify({ document, report, t }) {

package/lib/no-duplicate-dt/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for the `no-duplicate-dt` rule, categorized as validation. */
 declare const _default: {
     readonly category: "validation";
 };

package/lib/no-duplicate-dt/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for the `no-duplicate-dt` rule, categorized as validation. */
 export default {
     category: 'validation',
 };

package/lib/no-empty-palpable-content/index.d.ts

@@ -1,6 +1,19 @@
+/**
+ * Configuration options for the no-empty-palpable-content rule.
+ */
 type Options = {
+    /** Whether to extend checking to exposable elements beyond standard palpable content. */
     extendsExposableElements?: boolean;
+    /** Whether to ignore elements marked with `aria-busy="true"`. */
     ignoreIfAriaBusy?: boolean;
 };
+/**
+ * Rule that warns when palpable content elements are empty.
+ *
+ * Palpable content elements are expected to have visible or meaningful content.
+ * This rule reports elements that contain only whitespace text nodes, while
+ * excluding elements that are naturally empty (e.g., `<textarea>`, `<video>`)
+ * or have a nothing content model.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, Options>>;
 export default _default;

package/lib/no-empty-palpable-content/index.js

@@ -1,6 +1,10 @@
 import { createRule } from '@markuplint/ml-core';
 import { isNothingContentModel, isPalpableElement } from '@markuplint/ml-spec';
 import meta from './meta.js';
+/**
+ * Elements that are allowed to be empty because they are filled by user
+ * interaction or are inherently palpable by themselves.
+ */
 const allowedElements = new Set([
     // These elements are possibly empty because it to be filled by user interaction.
     'textarea',
@@ -11,6 +15,14 @@ const allowedElements = new Set([
     'video',
     'img',
 ]);
+/**
+ * Rule that warns when palpable content elements are empty.
+ *
+ * Palpable content elements are expected to have visible or meaningful content.
+ * This rule reports elements that contain only whitespace text nodes, while
+ * excluding elements that are naturally empty (e.g., `<textarea>`, `<video>`)
+ * or have a nothing content model.
+ */
 export default createRule({
     meta: meta,
     defaultSeverity: 'warning',

package/lib/no-empty-palpable-content/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for the `no-empty-palpable-content` rule, categorized as validation. */
 declare const _default: {
     readonly category: "validation";
 };

package/lib/no-empty-palpable-content/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for the `no-empty-palpable-content` rule, categorized as validation. */
 export default {
     category: 'validation',
 };

package/lib/no-hard-code-id/index.d.ts

@@ -1,2 +1,10 @@
+/**
+ * Rule that disallows hard-coded `id` attribute values in document fragments.
+ *
+ * Only active for fragment documents (e.g., component templates). Reports
+ * any `id` attribute whose value is a static string rather than a dynamic
+ * or code-generated value, encouraging dynamic ID generation to avoid
+ * collisions when fragments are reused.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<import("@markuplint/ml-core").RuleConfigValue, undefined>>;
 export default _default;

package/lib/no-hard-code-id/index.js

@@ -1,5 +1,13 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that disallows hard-coded `id` attribute values in document fragments.
+ *
+ * Only active for fragment documents (e.g., component templates). Reports
+ * any `id` attribute whose value is a static string rather than a dynamic
+ * or code-generated value, encouraging dynamic ID generation to avoid
+ * collisions when fragments are reused.
+ */
 export default createRule({
     meta: meta,
     defaultSeverity: 'warning',

package/lib/no-hard-code-id/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for `no-hard-code-id`: categorized as a maintainability rule. */
 declare const _default: {
     readonly category: "maintainability";
 };

package/lib/no-hard-code-id/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for `no-hard-code-id`: categorized as a maintainability rule. */
 export default {
     category: 'maintainability',
 };

package/lib/no-orphaned-end-tag/index.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Rule that detects orphaned end tags with no matching start tag.
+ *
+ * Scans text nodes and reports any that originated from invalid (bogus) AST
+ * nodes, which indicates a stray end tag that the parser could not match
+ * to an opening element.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, null>>;
 export default _default;

package/lib/no-orphaned-end-tag/index.js

@@ -1,11 +1,17 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that detects orphaned end tags with no matching start tag.
+ *
+ * Scans text nodes and reports any that originated from invalid (bogus) AST
+ * nodes, which indicates a stray end tag that the parser could not match
+ * to an opening element.
+ */
 export default createRule({
     meta,
     async verify({ document, report, t }) {
         await document.walkOn('Text', text => {
-            const raw = text.raw.trim();
-            if (/^<\//.test(raw)) {
+            if (text.isBogus) {
                 report({
                     scope: text,
                     message: t('{0} detected', t('Orphaned end tag')),

package/lib/no-orphaned-end-tag/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for `no-orphaned-end-tag`: categorized as a validation rule. */
 declare const _default: {
     readonly category: "validation";
 };

package/lib/no-orphaned-end-tag/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for `no-orphaned-end-tag`: categorized as a validation rule. */
 export default {
     category: 'validation',
 };

package/lib/no-refer-to-non-existent-id/index.d.ts

@@ -1,6 +1,14 @@
 import type { ARIAVersion } from '@markuplint/ml-spec';
+/**
+ * Rule that validates all ID references in attributes point to existing elements.
+ *
+ * Checks DOMID and DOMID-list attributes (e.g., `for`, `aria-labelledby`),
+ * ARIA ID reference properties, and fragment identifiers in hyperlinks (`href="#id"`).
+ * Reports any reference to an ID that does not exist in the document. Skips
+ * validation when dynamic IDs or preprocessor blocks are detected.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<import("@markuplint/ml-core").RuleConfigValue, {
-    ariaVersion: ARIAVersion;
+    ariaVersion: ARIAVersion | undefined;
     fragmentRefersNameAttr: boolean;
 }>>;
 export default _default;

package/lib/no-refer-to-non-existent-id/index.js

@@ -2,11 +2,20 @@ import { createRule, getAttrSpecs, ariaSpecs } from '@markuplint/ml-core';
 import { ARIA_RECOMMENDED_VERSION } from '@markuplint/ml-spec';
 import { decodeEntities, decodeHref } from '@markuplint/shared';
 import meta from './meta.js';
+/** CSS selector matching hyperlink elements that have an `href` attribute. */
 const HYPERLINK_SELECTOR = 'a[href], area[href]';
+/**
+ * Rule that validates all ID references in attributes point to existing elements.
+ *
+ * Checks DOMID and DOMID-list attributes (e.g., `for`, `aria-labelledby`),
+ * ARIA ID reference properties, and fragment identifiers in hyperlinks (`href="#id"`).
+ * Reports any reference to an ID that does not exist in the document. Skips
+ * validation when dynamic IDs or preprocessor blocks are detected.
+ */
 export default createRule({
     meta: meta,
     defaultOptions: {
-        ariaVersion: ARIA_RECOMMENDED_VERSION,
+        ariaVersion: undefined,
         fragmentRefersNameAttr: false,
     },
     async verify({ document, report, t }) {
@@ -91,7 +100,7 @@ export default createRule({
                     }
                 }
             }
-            const { props } = ariaSpecs(document.specs, attr.rule.options.ariaVersion);
+            const { props } = ariaSpecs(document.specs, attr.rule.options.ariaVersion ?? document.ruleCommonSettings?.ariaVersion ?? ARIA_RECOMMENDED_VERSION);
             const aria = props.find(prop => prop.name === name);
             if (aria) {
                 if (aria.value === 'ID reference' && !idList.has(value)) {

package/lib/no-refer-to-non-existent-id/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for the `no-refer-to-non-existent-id` rule, categorized as accessibility. */
 declare const _default: {
     readonly category: "a11y";
 };

package/lib/no-refer-to-non-existent-id/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for the `no-refer-to-non-existent-id` rule, categorized as accessibility. */
 export default {
     category: 'a11y',
 };

package/lib/no-unsupported-features/compat-data.d.ts

@@ -0,0 +1,71 @@
+import type { BrowserName, SupportStatement } from '@mdn/browser-compat-data';
+/**
+ * Target browser with name and minimum version.
+ */
+export interface TargetBrowser {
+    readonly browser: BrowserName;
+    readonly version: string;
+    readonly displayName: string;
+}
+/**
+ * Result of checking browser support for a feature.
+ */
+export interface UnsupportedResult {
+    readonly browser: BrowserName;
+    readonly displayName: string;
+    readonly targetVersion: string;
+    readonly addedVersion: string | false;
+    readonly removedVersion?: string;
+}
+/**
+ * Convert a browserslist browser name to a BCD browser name.
+ *
+ * @param browserslistName - The browser name from browserslist (e.g., "and_chr")
+ * @returns The corresponding BCD browser name, or null if unknown
+ */
+export declare function toBcdBrowserId(browserslistName: string): BrowserName | null;
+/**
+ * Parse a version string into a comparable numeric tuple.
+ *
+ * Handles BCD version prefixes like "≤37" by stripping the prefix.
+ *
+ * @param version - Version string (e.g., "16.4", "≤37", "preview")
+ * @returns Tuple of [major, minor, patch]
+ */
+export declare function parseVersion(version: string): readonly [number, number, number];
+/**
+ * Check if the target browser version satisfies the required version.
+ *
+ * Returns true if the target version is greater than or equal to the
+ * version the feature was added in.
+ *
+ * @param targetVersion - The browser version the user targets
+ * @param addedVersion - The version the feature was added in
+ * @returns Whether the target version supports the feature
+ */
+export declare function isVersionSatisfied(targetVersion: string, addedVersion: string): boolean;
+/**
+ * Check if a feature is supported by a specific browser version.
+ *
+ * @param support - The BCD support statement for the feature
+ * @param target - The target browser to check
+ * @returns null if supported or unknown, UnsupportedResult if not supported
+ */
+export declare function checkSupport(support: SupportStatement | undefined, target: TargetBrowser): UnsupportedResult | null;
+/**
+ * Check browser support for an HTML element.
+ *
+ * @param elementName - The HTML element name (e.g., "dialog")
+ * @param targets - Array of target browsers to check
+ * @returns Array of unsupported results (empty if all supported)
+ */
+export declare function checkElementSupport(elementName: string, targets: readonly TargetBrowser[]): Promise<readonly UnsupportedResult[]>;
+/**
+ * Check browser support for an HTML attribute on a specific element.
+ *
+ * @param elementName - The HTML element name (e.g., "input")
+ * @param attrName - The attribute name (e.g., "list")
+ * @param targets - Array of target browsers to check
+ * @returns Array of unsupported results (empty if all supported)
+ */
+export declare function checkAttributeSupport(elementName: string, attrName: string, targets: readonly TargetBrowser[]): Promise<readonly UnsupportedResult[]>;