praxis-kit 7.4.0 → 7.8.0

package/dist/html/index.js

@@ -1,18 +1,72 @@
-// ../../lib/contract/src/diagnostics/aria.ts
+// ../../lib/primitive/src/guards/foundational/is-defined.ts
+function isDefined(value) {
+  return value !== void 0;
+}
+
+// ../../lib/primitive/src/utils/type-guards.ts
+function isString(value) {
+  return typeof value === "string";
+}
+
+// ../../lib/contract/src/diagnostics/anchor-accessibility.ts
 import { DiagnosticCategory, DiagnosticCode } from "../_shared/diagnostics.js";
+function createDiagnostic(input) {
+  return { category: DiagnosticCategory.Accessibility, ...input };
+}
+var AnchorAccessibilityDiagnostics = {
+  roleButtonWithHref() {
+    return createDiagnostic({
+      code: DiagnosticCode.A11yAnchorRoleButtonWithHref,
+      severity: "warning",
+      message: 'role="button" on an <a> with an href overrides its navigation semantics for assistive technology; use a real <button> element, or remove href, if this element should not navigate.',
+      rationale: 'Assistive technology announces role="button" as a button, not a link \u2014 but the element still follows the link when activated by mouse or keyboard, which is confusing and inconsistent with how a button is expected to behave.',
+      suggestions: [
+        {
+          title: "Use a real <button>",
+          description: "If this element should not navigate, render a <button> instead of an <a>."
+        },
+        {
+          title: 'Remove role="button"',
+          description: "If this element should navigate, keep the default link role."
+        }
+      ]
+    });
+  },
+  ariaDisabledInert() {
+    return createDiagnostic({
+      code: DiagnosticCode.A11yAnchorAriaDisabledInert,
+      severity: "warning",
+      message: "aria-disabled does not prevent an <a> from being focused, clicked, or navigated via keyboard; remove href, or prevent navigation yourself, if this link should be inert.",
+      rationale: "Unlike a native form control, an <a> has no disabled state the browser enforces \u2014 aria-disabled only changes what assistive technology announces, not what actually happens when the link is activated by mouse or keyboard.",
+      suggestions: [
+        {
+          title: "Remove href",
+          description: "If this element is temporarily unavailable, remove href until it can be activated."
+        },
+        {
+          title: "Prevent navigation when disabled",
+          description: "Prevent the click and keyboard activation when the link is disabled so it behaves consistently for all users."
+        }
+      ]
+    });
+  }
+};
+
+// ../../lib/contract/src/diagnostics/aria.ts
+import { DiagnosticCategory as DiagnosticCategory2, DiagnosticCode as DiagnosticCode2 } from "../_shared/diagnostics.js";
 var AriaDiagnostics = {
   /** Generic bridge for violations produced by external AriaRule functions. */
   fromViolation(v) {
     return {
-      code: DiagnosticCode.AriaViolation,
-      category: DiagnosticCategory.ARIA,
+      code: DiagnosticCode2.AriaViolation,
+      category: DiagnosticCategory2.ARIA,
       message: v.message
     };
   },
   attributeInvalid(key, role) {
     return {
-      code: DiagnosticCode.AriaAttributeInvalid,
-      category: DiagnosticCategory.ARIA,
+      code: DiagnosticCode2.AriaAttributeInvalid,
+      category: DiagnosticCategory2.ARIA,
       message: `"${key}" is not valid on role="${role}". It will be removed.`,
       rationale: "Invalid ARIA attributes are ignored by assistive technology and may trigger accessibility-tree warnings in browser devtools.",
       suggestions: [
@@ -25,8 +79,8 @@ var AriaDiagnostics = {
   },
   missingLiveRegion(role, impliedLive) {
     return {
-      code: DiagnosticCode.AriaMissingLiveRegion,
-      category: DiagnosticCategory.ARIA,
+      code: DiagnosticCode2.AriaMissingLiveRegion,
+      category: DiagnosticCategory2.ARIA,
       message: `role="${role}" implies aria-live="${impliedLive}" but it is missing. It has been injected.`,
       rationale: "Live-region roles announce dynamic content changes to screen readers. Without aria-live the politeness level is unspecified and announcements may be silent.",
       suggestions: [
@@ -40,8 +94,8 @@ var AriaDiagnostics = {
   },
   missingAtomic(role) {
     return {
-      code: DiagnosticCode.AriaMissingAtomic,
-      category: DiagnosticCategory.ARIA,
+      code: DiagnosticCode2.AriaMissingAtomic,
+      category: DiagnosticCategory2.ARIA,
       message: `role="${role}" is a live region. Consider setting aria-atomic="true" if the full region should be announced as a unit, or aria-atomic="false" if only changed nodes should be read.`,
       rationale: "aria-atomic controls whether assistive technology announces the entire live region or only the changed nodes. Omitting it leaves the behaviour browser-defined."
     };
@@ -49,8 +103,8 @@ var AriaDiagnostics = {
   relevantInvalidTokens(invalid) {
     const quoted = invalid.map((t) => `"${t}"`).join(", ");
     return {
-      code: DiagnosticCode.AriaRelevantInvalidToken,
-      category: DiagnosticCategory.ARIA,
+      code: DiagnosticCode2.AriaRelevantInvalidToken,
+      category: DiagnosticCategory2.ARIA,
       message: `aria-relevant contains invalid token(s): ${quoted}. Valid tokens are: additions, removals, text, all.`,
       rationale: "aria-relevant accepts a space-separated list of change types. Unrecognised tokens are silently ignored by assistive technology, making the attribute ineffective.",
       suggestions: [
@@ -63,8 +117,8 @@ var AriaDiagnostics = {
   },
   relevantSuperseded() {
     return {
-      code: DiagnosticCode.AriaRelevantSuperseded,
-      category: DiagnosticCategory.ARIA,
+      code: DiagnosticCode2.AriaRelevantSuperseded,
+      category: DiagnosticCategory2.ARIA,
       message: 'aria-relevant includes "all" alongside other tokens. "all" supersedes additions, removals, and text \u2014 use aria-relevant="all" alone.',
       rationale: '"all" is equivalent to "additions removals text". Combining it with other tokens is redundant and may confuse readers of the markup.',
       suggestions: [
@@ -77,8 +131,8 @@ var AriaDiagnostics = {
   },
   missingAccessibleName(tag) {
     return {
-      code: DiagnosticCode.AriaMissingAccessibleName,
-      category: DiagnosticCategory.ARIA,
+      code: DiagnosticCode2.AriaMissingAccessibleName,
+      category: DiagnosticCategory2.ARIA,
       message: `<${tag}> has no accessible name. Add aria-label or aria-labelledby.`,
       rationale: "Elements with a landmark or interactive role must have an accessible name so that assistive technology can identify them when presenting the page outline.",
       suggestions: [
@@ -95,8 +149,8 @@ var AriaDiagnostics = {
   },
   attributeOnPresentational(attr, tag) {
     return {
-      code: DiagnosticCode.AriaAttributeOnPresentational,
-      category: DiagnosticCategory.ARIA,
+      code: DiagnosticCode2.AriaAttributeOnPresentational,
+      category: DiagnosticCategory2.ARIA,
       message: `"${attr}" is not allowed on a presentational <${tag}>. Presentational elements are invisible to assistive technology.`,
       rationale: 'role="none" and role="presentation" (including <img alt="">) remove an element from the accessibility tree. ARIA attributes on such elements are ignored by assistive technology.',
       suggestions: [
@@ -109,8 +163,8 @@ var AriaDiagnostics = {
   },
   ariaHiddenOnFocusable(tag) {
     return {
-      code: DiagnosticCode.AriaHiddenOnFocusable,
-      category: DiagnosticCategory.ARIA,
+      code: DiagnosticCode2.AriaHiddenOnFocusable,
+      category: DiagnosticCategory2.ARIA,
       message: `aria-hidden="true" must not be used on focusable <${tag}> elements. Screen reader users who navigate by keyboard will encounter the element but receive no information about it.`,
       rationale: 'aria-hidden removes an element from the accessibility tree while leaving it keyboard-reachable. This creates a "ghost" \u2014 a focusable element assistive technology cannot describe.',
       suggestions: [
@@ -128,8 +182,8 @@ var AriaDiagnostics = {
   invalidAttributeValue(attr, value, expected) {
     const got = value === null ? "null" : value === void 0 ? "undefined" : typeof value === "string" ? `"${value}"` : String(value);
     return {
-      code: DiagnosticCode.AriaInvalidAttributeValue,
-      category: DiagnosticCategory.ARIA,
+      code: DiagnosticCode2.AriaInvalidAttributeValue,
+      category: DiagnosticCategory2.ARIA,
       message: `"${attr}" has an invalid value (${got}). Expected: ${expected}.`,
       rationale: "ARIA attributes with invalid values are silently ignored by assistive technology, making the markup semantically inert.",
       suggestions: [
@@ -142,8 +196,8 @@ var AriaDiagnostics = {
   },
   redundantAriaLevel(tag, level) {
     return {
-      code: DiagnosticCode.AriaRedundantLevelAttribute,
-      category: DiagnosticCategory.ARIA,
+      code: DiagnosticCode2.AriaRedundantLevelAttribute,
+      category: DiagnosticCategory2.ARIA,
       message: `aria-level="${level}" is redundant on <${tag}>: the element already has an implicit heading level of ${level}. Remove the attribute.`,
       rationale: 'Restating the implicit aria-level adds noise without semantic value. Use aria-level only to override the native heading level (e.g. aria-level="3" on <h2>).',
       suggestions: [
@@ -156,8 +210,8 @@ var AriaDiagnostics = {
   },
   requiredProperty(attr, role) {
     return {
-      code: DiagnosticCode.AriaRequiredProperty,
-      category: DiagnosticCategory.ARIA,
+      code: DiagnosticCode2.AriaRequiredProperty,
+      category: DiagnosticCategory2.ARIA,
       message: `"${attr}" is required for role="${role}" but is missing.`,
       rationale: `WAI-ARIA 1.2 specifies required states and properties for certain roles. Without "${attr}", assistive technology cannot correctly communicate the element's state to users.`,
       suggestions: [
@@ -170,8 +224,8 @@ var AriaDiagnostics = {
   },
   invalidRole(role, tag) {
     return {
-      code: DiagnosticCode.AriaInvalidRole,
-      category: DiagnosticCategory.ARIA,
+      code: DiagnosticCode2.AriaInvalidRole,
+      category: DiagnosticCategory2.ARIA,
       message: `Invalid role "${role ?? ""}" on <${tag}>.`,
       rationale: "An unrecognised or misapplied ARIA role is ignored by assistive technology and may degrade the accessibility of the element."
     };
@@ -179,68 +233,68 @@ var AriaDiagnostics = {
 };
 
 // ../../lib/contract/src/diagnostics/html.ts
-import { DiagnosticCategory as DiagnosticCategory2, DiagnosticCode as DiagnosticCode2 } from "../_shared/diagnostics.js";
+import { DiagnosticCategory as DiagnosticCategory3, DiagnosticCode as DiagnosticCode3 } from "../_shared/diagnostics.js";
 var ATTRIBUTE_IGNORED_CODES = {
-  checked: DiagnosticCode2.HtmlInputCheckedIgnoredForType,
-  multiple: DiagnosticCode2.HtmlInputMultipleIgnoredForType,
-  maxLength: DiagnosticCode2.HtmlInputMaxLengthIgnoredForType,
-  minLength: DiagnosticCode2.HtmlInputMinLengthIgnoredForType,
-  pattern: DiagnosticCode2.HtmlInputPatternIgnoredForType,
-  min: DiagnosticCode2.HtmlInputMinIgnoredForType,
-  max: DiagnosticCode2.HtmlInputMaxIgnoredForType,
-  step: DiagnosticCode2.HtmlInputStepIgnoredForType,
-  accept: DiagnosticCode2.HtmlInputAcceptIgnoredForType,
-  capture: DiagnosticCode2.HtmlInputCaptureIgnoredForType,
-  size: DiagnosticCode2.HtmlInputSizeIgnoredForType,
-  alt: DiagnosticCode2.HtmlInputAltIgnoredForType,
-  height: DiagnosticCode2.HtmlInputHeightIgnoredForType,
-  width: DiagnosticCode2.HtmlInputWidthIgnoredForType
+  checked: DiagnosticCode3.HtmlInputCheckedIgnoredForType,
+  multiple: DiagnosticCode3.HtmlInputMultipleIgnoredForType,
+  maxLength: DiagnosticCode3.HtmlInputMaxLengthIgnoredForType,
+  minLength: DiagnosticCode3.HtmlInputMinLengthIgnoredForType,
+  pattern: DiagnosticCode3.HtmlInputPatternIgnoredForType,
+  min: DiagnosticCode3.HtmlInputMinIgnoredForType,
+  max: DiagnosticCode3.HtmlInputMaxIgnoredForType,
+  step: DiagnosticCode3.HtmlInputStepIgnoredForType,
+  accept: DiagnosticCode3.HtmlInputAcceptIgnoredForType,
+  capture: DiagnosticCode3.HtmlInputCaptureIgnoredForType,
+  size: DiagnosticCode3.HtmlInputSizeIgnoredForType,
+  alt: DiagnosticCode3.HtmlInputAltIgnoredForType,
+  height: DiagnosticCode3.HtmlInputHeightIgnoredForType,
+  width: DiagnosticCode3.HtmlInputWidthIgnoredForType
 };
 var HtmlDiagnostics = {
   emptyRole(tag) {
     return {
-      code: DiagnosticCode2.HtmlEmptyRole,
-      category: DiagnosticCategory2.HTML,
+      code: DiagnosticCode3.HtmlEmptyRole,
+      category: DiagnosticCategory3.HTML,
       severity: "warning",
       message: `<${tag}> has an explicit empty role="". Omit the attribute instead.`
     };
   },
   implicitRoleRedundant(tag, implicitRole) {
     return {
-      code: DiagnosticCode2.HtmlImplicitRoleRedundant,
-      category: DiagnosticCategory2.HTML,
+      code: DiagnosticCode3.HtmlImplicitRoleRedundant,
+      category: DiagnosticCategory3.HTML,
       severity: "warning",
       message: `<${tag}> already has implicit role="${implicitRole}". Avoid redundant role assignment.`
     };
   },
   implicitRoleOverride(tag, implicitRole, role) {
     return {
-      code: DiagnosticCode2.HtmlImplicitRoleOverride,
-      category: DiagnosticCategory2.HTML,
+      code: DiagnosticCode3.HtmlImplicitRoleOverride,
+      category: DiagnosticCategory3.HTML,
       severity: "error",
       message: `<${tag}> should not override its implicit role="${implicitRole}" with role="${role}".`
     };
   },
   standaloneRegionOverride(tag, implicitRole) {
     return {
-      code: DiagnosticCode2.HtmlStandaloneRegionOverride,
-      category: DiagnosticCategory2.HTML,
+      code: DiagnosticCode3.HtmlStandaloneRegionOverride,
+      category: DiagnosticCategory3.HTML,
       severity: "error",
       message: `<${tag}> is a self-contained element with implicit role="${implicitRole}". Assigning role="region" has been removed.`
     };
   },
   landmarkRoleOverride(tag, implicitRole, role) {
     return {
-      code: DiagnosticCode2.HtmlLandmarkRoleOverride,
-      category: DiagnosticCategory2.HTML,
+      code: DiagnosticCode3.HtmlLandmarkRoleOverride,
+      category: DiagnosticCategory3.HTML,
       severity: "error",
       message: `<${tag}> has a fixed landmark role="${implicitRole}". role="${role}" overrides it and confuses assistive technology. The override has been removed.`
     };
   },
   invalidChild(child, parent, allowed) {
     return {
-      code: DiagnosticCode2.HtmlInvalidChild,
-      category: DiagnosticCategory2.HTML,
+      code: DiagnosticCode3.HtmlInvalidChild,
+      category: DiagnosticCategory3.HTML,
       severity: "error",
       message: `<${child}> is not a valid direct child of <${parent}>. Allowed: ${allowed}.`
     };
@@ -248,8 +302,8 @@ var HtmlDiagnostics = {
   roleNotPermitted(tag, role, allowedRoles) {
     const allowed = allowedRoles.length > 0 ? allowedRoles.map((r) => `"${r}"`).join(", ") : "none \u2014 no explicit role is permitted on this element";
     return {
-      code: DiagnosticCode2.HtmlRoleNotPermitted,
-      category: DiagnosticCategory2.HTML,
+      code: DiagnosticCode3.HtmlRoleNotPermitted,
+      category: DiagnosticCategory3.HTML,
       severity: "error",
       message: `role="${role}" is not permitted on <${tag}>. Allowed alternate role(s): ${allowed}.`,
       rationale: 'The WAI-ARIA "ARIA in HTML" specification restricts which explicit roles a native element may take. A role outside that set is ignored or produces undefined behavior in assistive technology.'
@@ -260,8 +314,8 @@ var HtmlDiagnostics = {
   input: {
     unsupportedType(type) {
       return {
-        code: DiagnosticCode2.HtmlInputUnsupportedType,
-        category: DiagnosticCategory2.HTML,
+        code: DiagnosticCode3.HtmlInputUnsupportedType,
+        category: DiagnosticCategory3.HTML,
         severity: "warning",
         message: `type="${type}" is not a value defined by the HTML specification. Browsers silently fall back to type="text".`,
         rationale: 'An unrecognized input type is not invalid markup \u2014 the spec requires the "text" fallback \u2014 but it usually means a typo, since the input keeps working while silently losing the intended type-specific behavior (validation, virtual keyboard, picker UI).',
@@ -281,7 +335,7 @@ var HtmlDiagnostics = {
       if (!code) throw new Error(`No DiagnosticCode registered for input attribute "${attribute}"`);
       return {
         code,
-        category: DiagnosticCategory2.HTML,
+        category: DiagnosticCategory3.HTML,
         severity: "warning",
         message: `"${attribute}" is ignored on <input type="${type}">.`,
         rationale: `"${attribute}" only has an effect when type is one of: ${allowed}. Browsers silently ignore it on other input types.`,
@@ -293,18 +347,30 @@ var HtmlDiagnostics = {
         ]
       };
     }
+  },
+  // Reserved for <a>-specific facts (HTML3201–3299, see codes.ts).
+  anchor: {
+    dangerousHref(href) {
+      return {
+        code: DiagnosticCode3.HtmlAnchorDangerousHref,
+        category: DiagnosticCategory3.HTML,
+        severity: "warning",
+        message: `href="${href}" uses a scheme that executes attacker-controlled content when navigated to. It has been removed.`,
+        rationale: '"javascript:", "data:", and "vbscript:" URLs are a common XSS vector when href comes from untrusted input \u2014 none of the three are needed for legitimate navigation.'
+      };
+    }
   }
 };
 
 // ../../lib/contract/src/diagnostics/input-accessibility.ts
-import { DiagnosticCategory as DiagnosticCategory3, DiagnosticCode as DiagnosticCode3 } from "../_shared/diagnostics.js";
+import { DiagnosticCategory as DiagnosticCategory4, DiagnosticCode as DiagnosticCode4 } from "../_shared/diagnostics.js";
 function accessibilityFact(input) {
-  return { category: DiagnosticCategory3.Accessibility, ...input };
+  return { category: DiagnosticCategory4.Accessibility, ...input };
 }
 var InputAccessibilityDiagnostics = {
   missingAccessibleName() {
     return accessibilityFact({
-      code: DiagnosticCode3.A11yInputMissingAccessibleName,
+      code: DiagnosticCode4.A11yInputMissingAccessibleName,
       severity: "warning",
       message: "This input has no accessible name. Add an associated <label>, aria-label, or aria-labelledby.",
       rationale: "Assistive technology announces a form field by its accessible name; without one, users of screen readers cannot tell what the field is for.",
@@ -319,7 +385,7 @@ var InputAccessibilityDiagnostics = {
   },
   placeholderIsNotLabel() {
     return accessibilityFact({
-      code: DiagnosticCode3.A11yInputPlaceholderNotLabel,
+      code: DiagnosticCode4.A11yInputPlaceholderNotLabel,
       severity: "warning",
       message: "Placeholder text does not provide an accessible name. Add an associated <label>, aria-label, or aria-labelledby.",
       rationale: "Placeholder text disappears as users interact with the field and is not treated as the control's accessible name by many assistive technologies.",
@@ -334,7 +400,7 @@ var InputAccessibilityDiagnostics = {
   },
   passwordMissingAutocomplete() {
     return accessibilityFact({
-      code: DiagnosticCode3.A11yInputPasswordAutocomplete,
+      code: DiagnosticCode4.A11yInputPasswordAutocomplete,
       severity: "warning",
       message: "Password inputs should specify an autoComplete value.",
       rationale: "Without an explicit autocomplete hint, password managers and browsers cannot reliably tell a sign-in field apart from a password-creation field.",
@@ -352,7 +418,7 @@ var InputAccessibilityDiagnostics = {
   },
   requiredReadOnlyConflict() {
     return accessibilityFact({
-      code: DiagnosticCode3.A11yInputRequiredReadOnlyConflict,
+      code: DiagnosticCode4.A11yInputRequiredReadOnlyConflict,
       severity: "warning",
       message: "The required and readOnly attributes are both present. A read-only field cannot satisfy required validation through user interaction.",
       rationale: "This combination is valid HTML but usually indicates an unintended state. Consider using disabled instead of readOnly, or only applying required when the field is editable."
@@ -361,6 +427,27 @@ var InputAccessibilityDiagnostics = {
 };
 
 // ../../lib/contract/src/aria/factories.ts
+function invalidWithoutFix(input) {
+  return {
+    valid: false,
+    fixable: false,
+    severity: input.severity,
+    ...isDefined(input.attribute) && { attribute: input.attribute },
+    ...isDefined(input.message) && { message: input.message },
+    ...isDefined(input.diagnostic) && { diagnostic: input.diagnostic }
+  };
+}
+function invalidWithFix(input) {
+  return {
+    valid: false,
+    fixable: true,
+    severity: input.severity,
+    ...isDefined(input.attribute) && { attribute: input.attribute },
+    ...isDefined(input.message) && { message: input.message },
+    ...isDefined(input.diagnostic) && { diagnostic: input.diagnostic },
+    fix: input.fix
+  };
+}
 function removeProp(props, key) {
   const next = { ...props };
   delete next[key];
@@ -376,6 +463,34 @@ function removeAttributeFix(attribute) {
     }
   });
 }
+function defineRuleMetadata(rule, metadata) {
+  const descriptors = {};
+  for (const key of Object.keys(metadata)) {
+    descriptors[key] = { value: metadata[key], enumerable: false };
+  }
+  Object.defineProperties(rule, descriptors);
+  return rule;
+}
+function createRemoveAttributeRule(attribute, options) {
+  const { when, severity = "warning", message, diagnostic, readsProps, tags } = options;
+  const fix = removeAttributeFix(attribute);
+  const rule = (context) => {
+    if (!when(context)) return [];
+    return [
+      invalidWithFix({
+        severity,
+        attribute,
+        ...isDefined(message) && { message },
+        ...isDefined(diagnostic) && { diagnostic: diagnostic(context) },
+        fix
+      })
+    ];
+  };
+  return defineRuleMetadata(rule, {
+    ...isDefined(readsProps) && { readsProps },
+    ...isDefined(tags) && { tags }
+  });
+}
 
 // ../core/src/html/contracts/categories.ts
 var LANDMARK_TAGS = [
@@ -387,6 +502,52 @@ var LANDMARK_TAGS = [
   "nav"
 ];
 
+// ../core/src/html/anchor-rules.ts
+var DANGEROUS_URL_SCHEMES = ["javascript:", "data:", "vbscript:"];
+function normalizeForSchemeCheck(href) {
+  return href.replace(/[\x00-\x20]/g, "").toLowerCase();
+}
+function isDangerousUrl(href) {
+  if (!isString(href)) return false;
+  const normalized = normalizeForSchemeCheck(href);
+  return DANGEROUS_URL_SCHEMES.some((scheme) => normalized.startsWith(scheme));
+}
+var dangerousHrefRule = createRemoveAttributeRule("href", {
+  when: ({ props }) => isDangerousUrl(props.href),
+  severity: "warning",
+  diagnostic: ({ props }) => HtmlDiagnostics.anchor.dangerousHref(props.href),
+  readsProps: ["href"],
+  tags: ["a"]
+});
+var roleButtonWithHrefRule = Object.assign(
+  ({ props }) => {
+    if (props.role !== "button" || !isString(props.href) || props.href.length === 0) {
+      return [];
+    }
+    const diagnostic = AnchorAccessibilityDiagnostics.roleButtonWithHref();
+    return [invalidWithoutFix({ severity: diagnostic.severity, attribute: "role", diagnostic })];
+  },
+  { readsProps: ["role", "href"], tags: ["a"] }
+);
+var ariaDisabledInertRule = Object.assign(
+  ({ props }) => {
+    const ariaDisabled = props["aria-disabled"];
+    const isDisabled = ariaDisabled === true || ariaDisabled === "true";
+    const hasHref = isString(props.href) && props.href.length > 0;
+    if (!isDisabled || !hasHref) return [];
+    const diagnostic = AnchorAccessibilityDiagnostics.ariaDisabledInert();
+    return [
+      invalidWithoutFix({ severity: diagnostic.severity, attribute: "aria-disabled", diagnostic })
+    ];
+  },
+  { readsProps: ["aria-disabled", "href"], tags: ["a"] }
+);
+var ANCHOR_RULES = [
+  dangerousHrefRule,
+  roleButtonWithHrefRule,
+  ariaDisabledInertRule
+];
+
 // ../core/src/html/spec/vocabulary/input.ts
 var TEXT_INPUT_TYPES = ["text", "search", "url", "tel", "email", "password"];
 var NUMERIC_INPUT_TYPES = [
@@ -466,12 +627,12 @@ function createInputAttributeTypeRule({
 // ../core/src/html/spec/validators/mutually-exclusive-validator.ts
 function createMutuallyExclusiveRule({
   props: conflictingProps,
-  diagnostic: createDiagnostic
+  diagnostic: createDiagnostic2
 }) {
   const [first, second] = conflictingProps;
   const rule = ({ tag, props }) => {
     if (tag !== "input" || !props[first] || !props[second]) return [];
-    const diagnostic = createDiagnostic();
+    const diagnostic = createDiagnostic2();
     return [{ valid: false, fixable: false, severity: diagnostic.severity, diagnostic }];
   };
   return Object.assign(rule, { readsProps: conflictingProps, tags: ["input"] });
@@ -851,15 +1012,19 @@ var HTML_ARIA_RULES = [
   landmarkRoleRule,
   landmarkAccessibleNameRule,
   roleNotPermittedRule,
-  ...INPUT_RULES
+  ...INPUT_RULES,
+  ...ANCHOR_RULES
 ];
 export {
+  ANCHOR_RULES,
   HTML_ARIA_RULES,
   INPUT_RULES,
   acceptRequiresFileTypeRule,
   altRequiresImageTypeRule,
+  ariaDisabledInertRule,
   captureRequiresFileTypeRule,
   checkedRequiresCheckableTypeRule,
+  dangerousHrefRule,
   heightRequiresImageTypeRule,
   inputAccessibleNameRule,
   landmarkAccessibleNameRule,
@@ -873,6 +1038,7 @@ export {
   patternRequiresTextTypeRule,
   requireAccessibleName,
   requiredReadOnlyConflictRule,
+  roleButtonWithHrefRule,
   roleNotPermittedRule,
   sizeRequiresTextTypeRule,
   stepRequiresNumericTypeRule,

package/dist/lit/index.d.ts

@@ -72,6 +72,19 @@ type MergeRecords<A extends object, B extends object> = IsEmptyRecord<A> extends
 type IntrinsicTag = keyof HTMLElementTagNameMap;
 
 type ElementType = IntrinsicTag | (string & {});
+/**
+ * Resolves a component's default tag to its real DOM interface — `HTMLDialogElement` for
+ * `'dialog'`, `HTMLDetailsElement` for `'details'`, and so on — falling back to `HTMLElement`
+ * for custom-element tags or anything not in `HTMLElementTagNameMap`. Used to type
+ * `FactoryOptions.onElement`'s `element` param so component authors get direct, correctly-typed
+ * access to tag-specific native members (`dialogEl.showModal()`) without an unsafe cast.
+ *
+ * The fallback is `HTMLElement`, not the more generic `Element` — every tag reachable through
+ * `IntrinsicTag` extends it, and so does every custom element per spec, so members `HTMLElement`
+ * itself declares (`showPopover()`/`hidePopover()`/`togglePopover()`, the `popover` attribute)
+ * stay directly accessible even for tags with no dedicated entry in `HTMLElementTagNameMap`.
+ */
+type ElementForTag<TDefault extends ElementType> = TDefault extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[TDefault] : HTMLElement;
 
 declare const KNOWN_ARIA_ROLES: readonly ["alert", "alertdialog", "application", "article", "banner", "blockquote", "button", "caption", "cell", "checkbox", "code", "columnheader", "combobox", "complementary", "contentinfo", "definition", "deletion", "dialog", "document", "emphasis", "feed", "figure", "form", "generic", "grid", "gridcell", "group", "heading", "img", "insertion", "link", "list", "listbox", "listitem", "log", "main", "marquee", "math", "menu", "menubar", "menuitem", "menuitemcheckbox", "menuitemradio", "meter", "navigation", "none", "note", "option", "paragraph", "presentation", "progressbar", "radio", "radiogroup", "region", "row", "rowgroup", "rowheader", "scrollbar", "search", "searchbox", "separator", "slider", "spinbutton", "status", "strong", "subscript", "superscript", "switch", "tab", "table", "tablist", "tabpanel", "term", "textbox", "time", "timer", "toolbar", "tooltip", "tree", "treegrid", "treeitem"];
 type KnownAriaRole = (typeof KNOWN_ARIA_ROLES)[number];
@@ -171,7 +184,7 @@ type DefaultVariants<V extends VariantMap> = {
  * Presets are named bundles of variant props that callers activate by key,
  * avoiding the need to repeat variant combinations at each call site.
  */
-type RecipeMap<V extends VariantMap = VariantMap> = Readonly<Record<string, VariantSelection<V>>>;
+type RecipeMap<V extends VariantMap = VariantMap> = Readonly<StringMap<VariantSelection<V>>>;
 
 type RecipeTarget<TVariants extends VariantMap = VariantMap> = VariantSelection<TVariants>;
 
@@ -205,7 +218,7 @@ interface BaseClassOptions {
 type ClassPipelineFn = (tag: unknown, props: AnyRecord, className?: ClassName, recipe?: string) => string | undefined;
 
 interface RecipeOptions<TVariants extends VariantMap = VariantMap> {
-    recipeMap?: Record<string, RecipeTarget<TVariants>>;
+    recipeMap?: StringMap<RecipeTarget<TVariants>>;
 }
 
 interface TagMapOptions {
@@ -374,7 +387,7 @@ type StylingOptions<V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPre
      * combination, skipping runtime class computation entirely when a match is found. Normally
      * generated by a build-time class-extraction plugin rather than hand-authored.
      */
-    readonly precomputedClasses?: Readonly<Record<string, string>>;
+    readonly precomputedClasses?: Readonly<StringMap<string>>;
 };
 
 type NormalizeFn<Props extends AnyRecord = AnyRecord> = {
@@ -420,13 +433,23 @@ type FactoryOptions<TDefault extends ElementType = ElementType, Props extends An
      * no prop-based equivalent), not for anything expressible as a plain
      * prop.
      *
+     * `element` is typed to the real DOM interface of every tag the rendered
+     * element could actually be — `TDefault` plus whatever `enforcement.allowed`
+     * permits via `as` (`HTMLDialogElement` for `tag: 'dialog'`,
+     * `HTMLDetailsElement` for `tag: 'details'`, and so on) — no cast needed to
+     * reach tag-specific members. A component that leaves `allowed`
+     * unconstrained (any tag reachable via `as`) falls back to `HTMLElement`,
+     * which still covers members every element shares (`showPopover()` and
+     * friends); restrict `enforcement.allowed` to the tags `onElement`
+     * actually knows how to handle to get real narrowing.
+     *
      * `getProps` returns the instance's *current* resolved props at call
      * time — read it from inside a listener registered once at mount, rather
      * than re-subscribing on every prop change.
      *
      * Return a cleanup function to run when the instance unmounts.
      */
-    readonly onElement?: (element: Element, getProps: () => Readonly<Props>) => void | (() => void);
+    readonly onElement?: (element: ElementForTag<TDefault | TAllowed>, getProps: () => Readonly<Props>) => void | (() => void);
 };
 
 /**