@markuplint/rules 5.0.0-rc.2 → 5.0.0-rc.5

package/lib/require-dialog-autofocus/index.d.ts

@@ -1,19 +1,9 @@
 /**
- * Rule that requires a `<dialog>` element referenced by a `show-modal` command
- * to contain a descendant (or itself) with the `autofocus` attribute.
- *
  * Without `autofocus`, the browser's dialog focusing steps fall back to the
  * `<dialog>` element itself, which is not ideal for accessibility — screen
  * reader users may miss the dialog content, and keyboard users may need
  * extra tab presses to reach interactive elements.
  *
- * Detection algorithm:
- * 1. Find all `<button>` elements with both `command` and `commandfor` attributes
- * 2. Filter to triggers whose `command` value is `show-modal` (case-insensitive)
- * 3. Resolve the referenced `<dialog>` via `document.getElementById(commandfor)`
- * 4. Skip non-dialog targets and already-reported dialogs (deduplication)
- * 5. Report if neither the dialog nor any descendant has the `autofocus` attribute
- *
  * @see https://html.spec.whatwg.org/multipage/interactive-elements.html#dialog-focusing-steps
  * @see https://html.spec.whatwg.org/multipage/interactive-elements.html#the-dialog-element
  * @see https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/

package/lib/require-dialog-autofocus/index.js

@@ -1,21 +1,11 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
 /**
- * Rule that requires a `<dialog>` element referenced by a `show-modal` command
- * to contain a descendant (or itself) with the `autofocus` attribute.
- *
  * Without `autofocus`, the browser's dialog focusing steps fall back to the
  * `<dialog>` element itself, which is not ideal for accessibility — screen
  * reader users may miss the dialog content, and keyboard users may need
  * extra tab presses to reach interactive elements.
  *
- * Detection algorithm:
- * 1. Find all `<button>` elements with both `command` and `commandfor` attributes
- * 2. Filter to triggers whose `command` value is `show-modal` (case-insensitive)
- * 3. Resolve the referenced `<dialog>` via `document.getElementById(commandfor)`
- * 4. Skip non-dialog targets and already-reported dialogs (deduplication)
- * 5. Report if neither the dialog nor any descendant has the `autofocus` attribute
- *
  * @see https://html.spec.whatwg.org/multipage/interactive-elements.html#dialog-focusing-steps
  * @see https://html.spec.whatwg.org/multipage/interactive-elements.html#the-dialog-element
  * @see https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/

package/lib/require-dialog-autofocus/meta.d.ts

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

package/lib/require-dialog-autofocus/meta.js

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

package/lib/require-doctype/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<"always", undefined>>;
+export default _default;

package/lib/require-doctype/index.js

@@ -0,0 +1,19 @@
+import { createRule } from '@markuplint/ml-core';
+import meta from './meta.js';
+export default createRule({
+    meta: meta,
+    defaultValue: 'always',
+    verify({ document, report, t }) {
+        if (document.isFragment) {
+            return;
+        }
+        if (!document.doctype) {
+            report({
+                message: t('Require {0}', 'doctype'),
+                line: 1,
+                col: 1,
+                raw: '',
+            });
+        }
+    },
+});

package/lib/require-doctype/meta.d.ts

@@ -0,0 +1,5 @@
+declare const _default: {
+    readonly category: "structure";
+    readonly mirrorsParseErrorCodes: readonly ["missing-doctype"];
+};
+export default _default;

package/lib/require-doctype/meta.js

@@ -0,0 +1,10 @@
+export default {
+    category: 'structure',
+    // This rule covers parse5's `missing-doctype` event (the "no DOCTYPE at
+    // all" case). parse5's `non-conforming-doctype` and `misplaced-doctype`
+    // are NOT mirrored by either doctype rule — they have judgement criteria
+    // that differ from `no-obsolete-doctype` (e.g. parse5 flags
+    // `<!DOCTYPE HTML>` for uppercase, that rule does not). Users who want
+    // those should opt in via `severity.parseError` separately.
+    mirrorsParseErrorCodes: ['missing-doctype'],
+};

package/lib/{required-element → require-element}/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Configuration options for the required-element rule.
+ * Configuration options for the require-element rule.
  */
 type Options = {
     /** Whether to skip validation for elements that contain mutable (dynamic) content. */
@@ -7,13 +7,5 @@ type Options = {
     /** Whether to ignore omitted (ghost) elements that are implicitly created by the HTML parser. */
     ignoreOmittedElements: boolean;
 };
-/**
- * Rule that validates required child elements are present.
- *
- * Accepts an array of CSS selectors as the rule value. For the document level,
- * reports if any matching element is missing from the entire document. For
- * element-level overrides, checks that the specified child elements exist
- * among the element's direct children.
- */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<string[], Options>>;
 export default _default;

package/lib/{required-element → require-element}/index.js

@@ -1,13 +1,5 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
-/**
- * Rule that validates required child elements are present.
- *
- * Accepts an array of CSS selectors as the rule value. For the document level,
- * reports if any matching element is missing from the entire document. For
- * element-level overrides, checks that the specified child elements exist
- * among the element's direct children.
- */
 export default createRule({
     meta: meta,
     defaultValue: [],

package/lib/require-element/meta.d.ts

@@ -0,0 +1,4 @@
+declare const _default: {
+    readonly category: "structure";
+};
+export default _default;

package/lib/require-element/meta.js

@@ -0,0 +1,3 @@
+export default {
+    category: 'structure',
+};

package/lib/require-end-tag/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, undefined>>;
+export default _default;

package/lib/{end-tag → require-end-tag}/index.js

@@ -1,13 +1,6 @@
 import { createRule } from '@markuplint/ml-core';
 import { isVoidElement } from '@markuplint/ml-spec';
 import meta from './meta.js';
-/**
- * Rule that checks for missing end tags on non-void HTML elements.
- *
- * Reports elements that are neither void nor self-closing and have no
- * closing tag. Omitted elements and elements in documents configured
- * with `endTag: 'never'` are excluded.
- */
 export default createRule({
     meta: meta,
     defaultSeverity: 'warning',

package/lib/require-end-tag/meta.d.ts

@@ -0,0 +1,4 @@
+declare const _default: {
+    readonly category: "style";
+};
+export default _default;

package/lib/require-end-tag/meta.js

@@ -0,0 +1,3 @@
+export default {
+    category: 'style',
+};

package/lib/require-h1/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Configuration options for the `require-h1` rule.
+ */
+export interface Options {
+    /** Whether to apply this rule in document fragments (components, partials). */
+    'in-document-fragment': boolean;
+}
+/**
+ * Split from the former `required-h1` rule (#3989): the missing-`<h1>` half.
+ * Based on WCAG's Techniques H42 for Success Criterion 1.3.1 — a non-normative
+ * technique, not the criterion itself, so this rule's default severity is
+ * `warning`.
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Techniques/html/H42
+ */
+declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, Options>>;
+export default _default;

package/lib/{required-h1 → require-h1}/index.js

@@ -1,16 +1,17 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
 /**
- * Rule that requires exactly one `<h1>` element in the document.
+ * Split from the former `required-h1` rule (#3989): the missing-`<h1>` half.
+ * Based on WCAG's Techniques H42 for Success Criterion 1.3.1 — a non-normative
+ * technique, not the criterion itself, so this rule's default severity is
+ * `warning`.
  *
- * Reports a violation when no `<h1>` is present. Optionally reports when
- * multiple `<h1>` elements exist (controlled by `expected-once`). Can be
- * configured to skip document fragments via the `in-document-fragment` option.
+ * @see https://www.w3.org/WAI/WCAG21/Techniques/html/H42
  */
 export default createRule({
     meta: meta,
+    defaultSeverity: 'warning',
     defaultOptions: {
-        'expected-once': true,
         'in-document-fragment': false,
     },
     async verify({ document, report, t }) {
@@ -35,14 +36,5 @@ export default createRule({
                 raw: document.nodeList[0]?.raw.slice(0, 1) ?? '',
             });
         }
-        else if (document.rule.options['expected-once'] && h1Stack.length > 1 && h1Stack[1]) {
-            const message = t('{0} is {1:c}', t('the "{0*}" {1}', 'h1', 'element'), 'duplicated');
-            report({
-                message,
-                line: h1Stack[1].startLine,
-                col: h1Stack[1].startCol,
-                raw: h1Stack[1].raw,
-            });
-        }
     },
 });

package/lib/require-h1/meta.d.ts

@@ -0,0 +1,4 @@
+declare const _default: {
+    readonly category: "a11y";
+};
+export default _default;

package/lib/require-h1/meta.js

@@ -0,0 +1,3 @@
+export default {
+    category: 'a11y',
+};

package/lib/require-landmark-label/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Split from the former `landmark-roles` rule (#3989): when a document has
+ * more than one landmark of the same role, each occurrence needs a unique
+ * accessible name so assistive technology users can tell them apart, per
+ * APG's Landmark Regions practice. The former rule's `labelEachArea` option
+ * gated this check; disabling this rule entirely is how to opt out now.
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/
+ */
+declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, undefined>>;
+export default _default;

package/lib/require-landmark-label/index.js

@@ -0,0 +1,55 @@
+import { createRule } from '@markuplint/ml-core';
+import { computeLandmarkRoles } from '../landmark-roles/roles.js';
+import meta from './meta.js';
+/**
+ * Split from the former `landmark-roles` rule (#3989): when a document has
+ * more than one landmark of the same role, each occurrence needs a unique
+ * accessible name so assistive technology users can tell them apart, per
+ * APG's Landmark Regions practice. The former rule's `labelEachArea` option
+ * gated this check; disabling this rule entirely is how to opt out now.
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/
+ */
+export default createRule({
+    meta,
+    defaultSeverity: 'warning',
+    verify({ document, report, t }) {
+        if (document.isFragment) {
+            return;
+        }
+        const roles = computeLandmarkRoles(document);
+        for (const role of Object.keys(roles)) {
+            const roleEls = roles[role];
+            const duplicated = 1 < roleEls.length;
+            if (!duplicated) {
+                continue;
+            }
+            for (const el of roleEls) {
+                if (el.rule.disabled) {
+                    continue;
+                }
+                if (!hasLabel(el)) {
+                    report({
+                        scope: el,
+                        message: t('Require {0}', t('unique {0}', 'accessible name')),
+                    });
+                }
+            }
+        }
+    },
+});
+/**
+ * Checks whether an element has an accessible label via `aria-label` or `aria-labelledby`.
+ *
+ * @param el - The landmark element to check.
+ * @returns `true` if the element has an accessible name, `false` otherwise.
+ */
+function hasLabel(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el) {
+    const hasHeading = el.querySelectorAll('h1, h2, h3, h4, h5, h6').length > 0;
+    if (hasHeading && el.matches('[aria-labelledby]')) {
+        return true;
+    }
+    return el.matches('[aria-label]');
+}

package/lib/require-landmark-label/meta.d.ts

@@ -0,0 +1,4 @@
+declare const _default: {
+    readonly category: "a11y";
+};
+export default _default;

package/lib/require-landmark-label/meta.js

@@ -0,0 +1,3 @@
+export default {
+    category: 'a11y',
+};

package/lib/require-owned-elements/index.d.ts

@@ -0,0 +1,3 @@
+import type { Options } from '../wai-aria/types.js';
+declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, Options>>;
+export default _default;

package/lib/{wai-aria-required-owned-elements → require-owned-elements}/index.js

@@ -3,10 +3,8 @@ import { ARIA_RECOMMENDED_VERSION } from '@markuplint/ml-spec';
 import { checkingRequiredOwnedElements } from '../wai-aria/checkings/required-owned-elements.js';
 import { defaultOptions } from '../wai-aria/default-options.js';
 import meta from './meta.js';
-/** Warns when a role does not contain its required child roles. */
 export default createRule({
     meta,
-    defaultSeverity: 'warning',
     defaultOptions,
     async verify({ document, report }) {
         await document.walkOn('Element', el => {

package/lib/require-owned-elements/meta.d.ts

@@ -0,0 +1,4 @@
+declare const _default: {
+    readonly category: "a11y";
+};
+export default _default;

package/lib/require-owned-elements/meta.js

@@ -0,0 +1,3 @@
+export default {
+    category: 'a11y',
+};

package/lib/require-parent-role/index.d.ts

@@ -0,0 +1,3 @@
+import type { Options } from '../wai-aria/types.js';
+declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, Options>>;
+export default _default;

package/lib/{wai-aria-required-parent-role → require-parent-role}/index.js

@@ -3,7 +3,6 @@ import { ARIA_RECOMMENDED_VERSION } from '@markuplint/ml-spec';
 import { checkingRequiredAccessibilityParentRole } from '../wai-aria/checkings/required-accessibility-parent-role.js';
 import { defaultOptions } from '../wai-aria/default-options.js';
 import meta from './meta.js';
-/** Warns when an element with an explicit role is placed outside its required parent context. */
 export default createRule({
     meta,
     defaultOptions,

package/lib/require-parent-role/meta.d.ts

@@ -0,0 +1,4 @@
+declare const _default: {
+    readonly category: "a11y";
+};
+export default _default;

package/lib/require-parent-role/meta.js

@@ -0,0 +1,3 @@
+export default {
+    category: 'a11y',
+};

package/lib/role-supports-aria-prop/index.d.ts

@@ -0,0 +1,8 @@
+import type { Options } from '../wai-aria/types.js';
+/**
+ * Split from the former `wai-aria-disallowed-props` rule (#3989): the
+ * role-derived "supported states and properties" check alone. See
+ * `checkingRoleSupportsAriaProp`'s JSDoc for the full spec citation.
+ */
+declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, Options>>;
+export default _default;

package/lib/{wai-aria-disallowed-props → role-supports-aria-prop}/index.js

@@ -1,18 +1,24 @@
 import { createRule, getComputedRole, ariaSpecs, getSpec } from '@markuplint/ml-core';
 import { ARIA_RECOMMENDED_VERSION } from '@markuplint/ml-spec';
-import { checkingDisallowedProp } from '../wai-aria/checkings/disallowed-prop.js';
+import { checkingRoleSupportsAriaProp } from '../wai-aria/checkings/role-supports-aria-prop.js';
 import { defaultOptions } from '../wai-aria/default-options.js';
 import meta from './meta.js';
-/** Warns when an ARIA property or state is not allowed on the element's computed role. */
+/**
+ * Split from the former `wai-aria-disallowed-props` rule (#3989): the
+ * role-derived "supported states and properties" check alone. See
+ * `checkingRoleSupportsAriaProp`'s JSDoc for the full spec citation.
+ */
 export default createRule({
     meta,
     defaultOptions,
     async verify({ document, report }) {
         await document.walkOn('Element', el => {
             const elSpec = getSpec(el, document.specs.specs);
-            if (!elSpec)
+            // Autonomous custom elements have no spec.<el>.jsonc entry and no
+            // computed role for this checker to key on.
+            if (!elSpec && el.elementType !== 'web-component')
                 return;
-            if (!elSpec.globalAttrs['#ARIAAttrs'])
+            if (elSpec && !elSpec.globalAttrs['#ARIAAttrs'])
                 return;
             const propAttrs = el.attributes.filter(attr => /^aria-/i.test(attr.name));
             if (propAttrs.length === 0)
@@ -21,12 +27,7 @@ export default createRule({
             const computed = getComputedRole(document.specs, el, ariaVersion);
             const { props: propSpecs } = ariaSpecs(document.specs, ariaVersion);
             for (const attr of propAttrs) {
-                report(checkingDisallowedProp({
-                    attr,
-                    role: computed.role,
-                    propSpecs,
-                    disallowSetImplicitProps: true,
-                }));
+                report(checkingRoleSupportsAriaProp({ attr, role: computed.role, propSpecs }));
             }
         });
     },

package/lib/role-supports-aria-prop/meta.d.ts

@@ -0,0 +1,4 @@
+declare const _default: {
+    readonly category: "a11y";
+};
+export default _default;

package/lib/role-supports-aria-prop/meta.js

@@ -0,0 +1,3 @@
+export default {
+    category: 'a11y',
+};

package/lib/rule-aliases.d.ts

@@ -0,0 +1,2 @@
+import type { RuleAliasTable } from '@markuplint/ml-config';
+export declare const ruleAliasTable: RuleAliasTable;