praxis-kit 6.2.0 → 6.2.3

package/dist/lit/index.js

@@ -858,11 +858,24 @@ var ContractDiagnostics = {
 
 // ../../lib/contract/src/diagnostics/html.ts
 import { DiagnosticCategory as DiagnosticCategory3, DiagnosticCode as DiagnosticCode3 } from "../_shared/diagnostics.js";
+var ATTRIBUTE_IGNORED_CODES = {
+  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
+};
 var HtmlDiagnostics = {
   emptyRole(tag) {
     return {
       code: DiagnosticCode3.HtmlEmptyRole,
       category: DiagnosticCategory3.HTML,
+      severity: "warning",
       message: `<${tag}> has an explicit empty role="". Omit the attribute instead.`
     };
   },
@@ -870,6 +883,7 @@ var HtmlDiagnostics = {
     return {
       code: DiagnosticCode3.HtmlImplicitRoleRedundant,
       category: DiagnosticCategory3.HTML,
+      severity: "warning",
       message: `<${tag}> already has implicit role="${implicitRole}". Avoid redundant role assignment.`
     };
   },
@@ -877,6 +891,7 @@ var HtmlDiagnostics = {
     return {
       code: DiagnosticCode3.HtmlImplicitRoleOverride,
       category: DiagnosticCategory3.HTML,
+      severity: "error",
       message: `<${tag}> should not override its implicit role="${implicitRole}" with role="${role}".`
     };
   },
@@ -884,6 +899,7 @@ var HtmlDiagnostics = {
     return {
       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.`
     };
   },
@@ -891,6 +907,7 @@ var HtmlDiagnostics = {
     return {
       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.`
     };
   },
@@ -898,8 +915,122 @@ var HtmlDiagnostics = {
     return {
       code: DiagnosticCode3.HtmlInvalidChild,
       category: DiagnosticCategory3.HTML,
+      severity: "error",
       message: `<${child}> is not a valid direct child of <${parent}>. Allowed: ${allowed}.`
     };
+  },
+  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: 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.'
+    };
+  },
+  // Reserved for <input>-specific facts (HTML3101–3199, see codes.ts) — later element families
+  // (button, img, table, ...) get their own reserved block and their own namespace here.
+  input: {
+    unsupportedType(type) {
+      return {
+        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).',
+        suggestions: [
+          {
+            title: "Check for a typo in the type value",
+            description: `"${type}" does not match any HTML5 input type.`
+          }
+        ]
+      };
+    },
+    // The user-visible problem is that the attribute is ignored — not that it "requires" a type;
+    // that's the rule's internal framing, not what the browser actually does.
+    attributeIgnoredForType(attribute, type, allowedTypes) {
+      const allowed = allowedTypes.map((t) => `"${t}"`).join(", ");
+      const code = ATTRIBUTE_IGNORED_CODES[attribute];
+      if (!code) throw new Error(`No DiagnosticCode registered for input attribute "${attribute}"`);
+      return {
+        code,
+        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.`,
+        suggestions: [
+          {
+            title: `Remove "${attribute}"`,
+            description: `"${attribute}" only affects <input> when type is one of: ${allowed}.`
+          }
+        ]
+      };
+    }
+  }
+};
+
+// ../../lib/contract/src/diagnostics/input-accessibility.ts
+import { DiagnosticCategory as DiagnosticCategory4, DiagnosticCode as DiagnosticCode4 } from "../_shared/diagnostics.js";
+function accessibilityFact(input) {
+  return { category: DiagnosticCategory4.Accessibility, ...input };
+}
+var InputAccessibilityDiagnostics = {
+  missingAccessibleName() {
+    return accessibilityFact({
+      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.",
+      suggestions: [
+        { title: "Add aria-label", description: 'Set aria-label="\u2026" directly on the input.' },
+        {
+          title: "Add an associated <label>",
+          description: 'Wrap the input in a <label>, or point a <label for="\u2026"> at its id.'
+        }
+      ]
+    });
+  },
+  placeholderIsNotLabel() {
+    return accessibilityFact({
+      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.",
+      suggestions: [
+        { title: "Add aria-label", description: 'Set aria-label="\u2026" directly on the input.' },
+        {
+          title: "Add an associated <label>",
+          description: 'Wrap the input in a <label>, or point a <label for="\u2026"> at its id.'
+        }
+      ]
+    });
+  },
+  passwordMissingAutocomplete() {
+    return accessibilityFact({
+      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.",
+      suggestions: [
+        {
+          title: 'Set autoComplete="current-password"',
+          description: "Use this for sign-in forms."
+        },
+        {
+          title: 'Set autoComplete="new-password"',
+          description: "Use this for sign-up / change-password forms."
+        }
+      ]
+    });
+  },
+  requiredReadOnlyConflict() {
+    return accessibilityFact({
+      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."
+    });
   }
 };
 
@@ -958,7 +1089,7 @@ var AriaPolicyEngine = class _AriaPolicyEngine extends InvariantBase {
             tag,
             role: "",
             attribute: void 0,
-            severity: "warning",
+            severity: d.severity,
             phase: "evaluate"
           }
         ]
@@ -1217,13 +1348,14 @@ var AriaPolicyEngine = class _AriaPolicyEngine extends InvariantBase {
     const role = props.role;
     if (!implicitRole || !role || role === implicitRole) return NO_VIOLATIONS;
     if (isStrongImplicitRole(tag) && role === "region") {
+      const diagnostic = HtmlDiagnostics.implicitRoleOverride(tag, implicitRole, role);
       return [
         {
           valid: false,
           fixable: true,
-          severity: "error",
+          severity: diagnostic.severity,
           fix: _AriaPolicyEngine.#removeRole,
-          diagnostic: HtmlDiagnostics.implicitRoleOverride(tag, implicitRole, role)
+          diagnostic
         }
       ];
     }
@@ -1232,13 +1364,14 @@ var AriaPolicyEngine = class _AriaPolicyEngine extends InvariantBase {
   static #checkRedundantRole({ tag, props, implicitRole }) {
     const role = props.role;
     if (!implicitRole || !role || role !== implicitRole) return NO_VIOLATIONS;
+    const diagnostic = HtmlDiagnostics.implicitRoleRedundant(tag, implicitRole);
     return [
       {
         valid: false,
         fixable: true,
-        severity: "warning",
+        severity: diagnostic.severity,
         fix: _AriaPolicyEngine.#removeRole,
-        diagnostic: HtmlDiagnostics.implicitRoleRedundant(tag, implicitRole)
+        diagnostic
       }
     ];
   }
@@ -1246,13 +1379,14 @@ var AriaPolicyEngine = class _AriaPolicyEngine extends InvariantBase {
     const role = props.role;
     if (role !== "region") return NO_VIOLATIONS;
     if (!isStandaloneTag(tag)) return NO_VIOLATIONS;
+    const diagnostic = HtmlDiagnostics.standaloneRegionOverride(tag, implicitRole ?? tag);
     return [
       {
         valid: false,
         fixable: true,
-        severity: "error",
+        severity: diagnostic.severity,
         fix: _AriaPolicyEngine.#removeRole,
-        diagnostic: HtmlDiagnostics.standaloneRegionOverride(tag, implicitRole ?? tag)
+        diagnostic
       }
     ];
   }
@@ -1941,6 +2075,331 @@ var readonlyProps = ({
 // ../core/src/html/evaluators.ts
 import { warnDiagnostics as warnDiagnostics2 } from "../_shared/diagnostics.js";
 
+// ../core/src/html/input-rules.ts
+var DEFAULT_INPUT_TYPE = "text";
+function omit(props, key) {
+  const next = { ...props };
+  delete next[key];
+  return next;
+}
+function removeAttributeFix(attribute) {
+  return {
+    kind: `removeAttribute:${attribute}`,
+    apply: ({ props }) => {
+      if (!(attribute in props)) return { applied: false, next: props };
+      return { applied: true, next: omit(props, attribute), previous: props };
+    }
+  };
+}
+function inputAttributeRequiresType(attribute, allowedTypes) {
+  const rule = ({ tag, props }) => {
+    if (tag !== "input" || !(attribute in props)) return [];
+    const type = typeof props.type === "string" ? props.type : DEFAULT_INPUT_TYPE;
+    if (allowedTypes.includes(type)) return [];
+    const diagnostic = HtmlDiagnostics.input.attributeIgnoredForType(attribute, type, allowedTypes);
+    return [
+      {
+        valid: false,
+        fixable: true,
+        severity: diagnostic.severity,
+        fix: removeAttributeFix(attribute),
+        diagnostic
+      }
+    ];
+  };
+  return Object.assign(rule, { readsProps: ["type", attribute] });
+}
+var TEXT_INPUT_TYPES = ["text", "search", "url", "tel", "email", "password"];
+var NUMERIC_INPUT_TYPES = [
+  "number",
+  "range",
+  "date",
+  "month",
+  "week",
+  "time",
+  "datetime-local"
+];
+var HTML_INPUT_TYPES = /* @__PURE__ */ new Set([
+  ...TEXT_INPUT_TYPES,
+  ...NUMERIC_INPUT_TYPES,
+  "checkbox",
+  "radio",
+  "file",
+  "color",
+  "hidden",
+  "button",
+  "submit",
+  "reset",
+  "image"
+]);
+var supportedInputTypeRule = Object.assign(
+  ({ tag, props }) => {
+    if (tag !== "input" || typeof props.type !== "string") return [];
+    const type = props.type;
+    if (HTML_INPUT_TYPES.has(type)) return [];
+    const diagnostic = HtmlDiagnostics.input.unsupportedType(type);
+    return [
+      {
+        valid: false,
+        fixable: false,
+        severity: diagnostic.severity,
+        diagnostic
+      }
+    ];
+  },
+  { readsProps: ["type"] }
+);
+var checkedRequiresCheckableTypeRule = inputAttributeRequiresType("checked", [
+  "checkbox",
+  "radio"
+]);
+var multipleRequiresSupportedTypeRule = inputAttributeRequiresType("multiple", [
+  "email",
+  "file"
+]);
+var maxLengthRequiresTextTypeRule = inputAttributeRequiresType(
+  "maxLength",
+  TEXT_INPUT_TYPES
+);
+var minLengthRequiresTextTypeRule = inputAttributeRequiresType(
+  "minLength",
+  TEXT_INPUT_TYPES
+);
+var patternRequiresTextTypeRule = inputAttributeRequiresType("pattern", TEXT_INPUT_TYPES);
+var minRequiresNumericTypeRule = inputAttributeRequiresType("min", NUMERIC_INPUT_TYPES);
+var maxRequiresNumericTypeRule = inputAttributeRequiresType("max", NUMERIC_INPUT_TYPES);
+var stepRequiresNumericTypeRule = inputAttributeRequiresType("step", NUMERIC_INPUT_TYPES);
+var acceptRequiresFileTypeRule = inputAttributeRequiresType("accept", ["file"]);
+var captureRequiresFileTypeRule = inputAttributeRequiresType("capture", ["file"]);
+var inputAccessibleNameRule = Object.assign(
+  ({ tag, props }) => {
+    if (tag !== "input" || props.type === "hidden") return [];
+    if ("aria-label" in props || "aria-labelledby" in props) return [];
+    const hasPlaceholder = typeof props.placeholder === "string" && props.placeholder.length > 0;
+    const diagnostic = hasPlaceholder ? InputAccessibilityDiagnostics.placeholderIsNotLabel() : InputAccessibilityDiagnostics.missingAccessibleName();
+    return [{ valid: false, fixable: false, severity: diagnostic.severity, diagnostic }];
+  },
+  { readsProps: ["type", "aria-label", "aria-labelledby", "placeholder"] }
+);
+var PASSWORD_AUTOCOMPLETE_VALUES = ["current-password", "new-password"];
+var passwordAutocompleteRule = Object.assign(
+  ({ tag, props }) => {
+    if (tag !== "input" || props.type !== "password") return [];
+    const autoComplete = props.autoComplete;
+    const tokens = typeof autoComplete === "string" ? autoComplete.split(" ") : [];
+    if (PASSWORD_AUTOCOMPLETE_VALUES.some((value) => tokens.includes(value))) return [];
+    const diagnostic = InputAccessibilityDiagnostics.passwordMissingAutocomplete();
+    return [{ valid: false, fixable: false, severity: diagnostic.severity, diagnostic }];
+  },
+  { readsProps: ["type", "autoComplete"] }
+);
+var requiredReadOnlyConflictRule = Object.assign(
+  ({ tag, props }) => {
+    if (tag !== "input" || !props.required || !props.readOnly) return [];
+    const diagnostic = InputAccessibilityDiagnostics.requiredReadOnlyConflict();
+    return [{ valid: false, fixable: false, severity: diagnostic.severity, diagnostic }];
+  },
+  { readsProps: ["required", "readOnly"] }
+);
+var INPUT_RULES = [
+  supportedInputTypeRule,
+  checkedRequiresCheckableTypeRule,
+  multipleRequiresSupportedTypeRule,
+  maxLengthRequiresTextTypeRule,
+  minLengthRequiresTextTypeRule,
+  patternRequiresTextTypeRule,
+  minRequiresNumericTypeRule,
+  maxRequiresNumericTypeRule,
+  stepRequiresNumericTypeRule,
+  acceptRequiresFileTypeRule,
+  captureRequiresFileTypeRule,
+  inputAccessibleNameRule,
+  passwordAutocompleteRule,
+  requiredReadOnlyConflictRule
+];
+
+// ../core/src/html/role-restrictions.ts
+var ALLOWED_ROLES = {
+  article: ["application", "document", "feed", "main", "none", "presentation", "region"],
+  aside: ["feed", "none", "presentation", "region", "search"],
+  footer: ["group", "none", "presentation"],
+  header: ["group", "none", "presentation"],
+  main: [],
+  nav: [],
+  a: [
+    "button",
+    "checkbox",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "option",
+    "radio",
+    "switch",
+    "tab",
+    "treeitem"
+  ],
+  button: [
+    "checkbox",
+    "link",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "option",
+    "radio",
+    "switch",
+    "tab"
+  ],
+  select: ["menu"],
+  h1: ["tab", "presentation", "none"],
+  h2: ["tab", "presentation", "none"],
+  h3: ["tab", "presentation", "none"],
+  h4: ["tab", "presentation", "none"],
+  h5: ["tab", "presentation", "none"],
+  h6: ["tab", "presentation", "none"],
+  ul: [
+    "directory",
+    "group",
+    "listbox",
+    "menu",
+    "menubar",
+    "radiogroup",
+    "tablist",
+    "toolbar",
+    "tree"
+  ],
+  ol: [
+    "directory",
+    "group",
+    "listbox",
+    "menu",
+    "menubar",
+    "radiogroup",
+    "tablist",
+    "toolbar",
+    "tree"
+  ],
+  li: [
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "option",
+    "none",
+    "presentation",
+    "radio",
+    "separator",
+    "tab",
+    "treeitem"
+  ],
+  table: ["grid", "treegrid"],
+  dialog: ["alertdialog"],
+  fieldset: ["none", "presentation", "radiogroup"]
+};
+var IMG_NAMED_ROLES = [
+  "button",
+  "checkbox",
+  "link",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "option",
+  "progressbar",
+  "scrollbar",
+  "separator",
+  "slider",
+  "switch",
+  "tab",
+  "treeitem"
+];
+var ALLOWED_INPUT_ROLES = {
+  checkbox: ["menuitemcheckbox", "option", "switch", "button"],
+  radio: ["menuitemradio"],
+  range: [],
+  number: [],
+  search: ["combobox"],
+  text: ["combobox", "searchbox", "spinbutton"],
+  email: ["combobox"],
+  tel: ["combobox"],
+  url: ["combobox"],
+  button: [
+    "link",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "option",
+    "radio",
+    "switch",
+    "tab"
+  ],
+  submit: [
+    "link",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "option",
+    "radio",
+    "switch",
+    "tab"
+  ],
+  reset: [
+    "link",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "option",
+    "radio",
+    "switch",
+    "tab"
+  ],
+  image: [
+    "link",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "option",
+    "radio",
+    "switch",
+    "tab"
+  ],
+  hidden: []
+};
+function getAllowedRoles(tag, props) {
+  if (tag === "input") {
+    const type = typeof props.type === "string" ? props.type : "text";
+    return ALLOWED_INPUT_ROLES[type];
+  }
+  if (tag === "img") {
+    return props.alt === "" ? [] : IMG_NAMED_ROLES;
+  }
+  return ALLOWED_ROLES[tag];
+}
+var removeRoleFix = {
+  kind: "removeRole",
+  apply: ({ props }) => {
+    if (!("role" in props)) return { applied: false, next: props };
+    const { role: _role, ...rest } = props;
+    return { applied: true, next: rest, previous: props };
+  }
+};
+var roleNotPermittedRule = Object.assign(
+  ({ tag, props, implicitRole }) => {
+    const role = props.role;
+    if (typeof role !== "string" || role.length === 0 || role === implicitRole) return [];
+    const allowed = getAllowedRoles(tag, props);
+    if (allowed === void 0 || allowed.includes(role)) return [];
+    const diagnostic = HtmlDiagnostics.roleNotPermitted(tag, role, allowed);
+    return [
+      {
+        valid: false,
+        fixable: true,
+        severity: diagnostic.severity,
+        fix: removeRoleFix,
+        diagnostic
+      }
+    ];
+  },
+  { readsProps: ["role", "type", "alt"] }
+);
+
 // ../core/src/html/aria-rules.ts
 var LANDMARK_TAG_SET = /* @__PURE__ */ new Set(["article", "aside", "footer", "header", "main", "nav"]);
 var removeLandmarkRoleOverride = {
@@ -1955,13 +2414,14 @@ function landmarkRoleRule({ tag, props, implicitRole }) {
   if (!LANDMARK_TAG_SET.has(tag) || !implicitRole) return [];
   const role = props.role;
   if (!role || role === implicitRole) return [];
+  const diagnostic = HtmlDiagnostics.landmarkRoleOverride(tag, implicitRole, role);
   return [
     {
       valid: false,
       fixable: true,
-      severity: "error",
+      severity: diagnostic.severity,
       fix: removeLandmarkRoleOverride,
-      diagnostic: HtmlDiagnostics.landmarkRoleOverride(tag, implicitRole, role)
+      diagnostic
     }
   ];
 }
@@ -1981,7 +2441,12 @@ function landmarkNameAdvisory(ctx) {
   if (!ctx.implicitRole || !NAMED_LANDMARK_TAGS.has(ctx.tag)) return [];
   return requireAccessibleName(ctx);
 }
-var HTML_ARIA_RULES = [landmarkRoleRule, landmarkNameAdvisory];
+var HTML_ARIA_RULES = [
+  landmarkRoleRule,
+  landmarkNameAdvisory,
+  roleNotPermittedRule,
+  ...INPUT_RULES
+];
 
 // ../core/src/html/contracts.ts
 import { warnDiagnostics } from "../_shared/diagnostics.js";
@@ -2442,21 +2907,21 @@ function validateRenderProps(diagnostics, options, props, recipeKey) {
 import { throwDiagnostics } from "../_shared/diagnostics.js";
 
 // ../core/src/factory/plugin-diagnostics.ts
-import { DiagnosticCategory as DiagnosticCategory4, DiagnosticCode as DiagnosticCode4 } from "../_shared/diagnostics.js";
+import { DiagnosticCategory as DiagnosticCategory5, DiagnosticCode as DiagnosticCode5 } from "../_shared/diagnostics.js";
 var PluginDiagnostics = {
   invalidShape(received) {
     const got = received === null ? "null" : typeof received;
     return {
-      code: DiagnosticCode4.PluginInvalidShape,
-      category: DiagnosticCategory4.Internal,
+      code: DiagnosticCode5.PluginInvalidShape,
+      category: DiagnosticCategory5.Internal,
       message: `[praxis-kit] Plugin factory must return an object with a 'pipeline' function. Got: ${got}.`
     };
   },
   pipelineReturnType(received) {
     const got = received === null ? "null" : Array.isArray(received) ? "array" : typeof received;
     return {
-      code: DiagnosticCode4.PluginPipelineReturnType,
-      category: DiagnosticCategory4.Internal,
+      code: DiagnosticCode5.PluginPipelineReturnType,
+      category: DiagnosticCategory5.Internal,
       message: `[praxis-kit] Plugin pipeline must return a string. Got: ${got}.`
     };
   }