@jay-framework/a11y-validator 0.22.2 → 0.23.1

package/dist/index.js

@@ -1,4 +1,11 @@
 import { walkElements } from "@jay-framework/compiler-shared";
+const A11Y_GUIDE = "\nSee: agent-kit/designer/a11y-patterns.md";
+function pushFinding(findings, finding) {
+  if (finding.suggestion) {
+    finding.suggestion += A11Y_GUIDE;
+  }
+  findings.push(finding);
+}
 const INTERACTIVE_ELEMENTS = /* @__PURE__ */ new Set(["a", "button", "input", "select", "textarea"]);
 const NON_INTERACTIVE_ELEMENTS = /* @__PURE__ */ new Set([
   "div",
@@ -87,6 +94,19 @@ const VALID_ARIA_ROLES = /* @__PURE__ */ new Set([
   "treegrid",
   "treeitem"
 ]);
+const INTERACTIVE_CONTAINER_ROLES = /* @__PURE__ */ new Set(["button", "link"]);
+const WIDGET_ROLES = /* @__PURE__ */ new Set([
+  "button",
+  "link",
+  "checkbox",
+  "radio",
+  "switch",
+  "tab",
+  "menuitem",
+  "option",
+  "textbox"
+]);
+const FOCUSABLE_ELEMENTS = /* @__PURE__ */ new Set(["button", "select", "textarea", "summary"]);
 const LABELABLE_INPUTS = /* @__PURE__ */ new Set([
   "text",
   "password",
@@ -102,20 +122,35 @@ const LABELABLE_INPUTS = /* @__PURE__ */ new Set([
   "week",
   "color",
   "file",
-  "range"
+  "range",
+  "checkbox",
+  "radio"
 ]);
+const IGNORED_INPUT_TYPES = /* @__PURE__ */ new Set(["hidden", "submit", "button", "reset"]);
 const validate = (ctx) => {
   const findings = [];
   const labelForIds = /* @__PURE__ */ new Set();
-  collectLabelForIds(ctx.body, labelForIds);
+  const allIds = /* @__PURE__ */ new Set();
+  const idCounts = /* @__PURE__ */ new Map();
+  collectDomIndex(ctx.body, labelForIds, allIds, idCounts);
+  for (const [id, count] of idCounts) {
+    if (count > 1) {
+      pushFinding(findings, {
+        severity: "error",
+        message: `Duplicate id="${id}" used ${count} times (WCAG 4.1.1)`,
+        suggestion: "Give each element a unique id. Duplicate ids break label associations and ARIA references.",
+        attribute: "id"
+      });
+    }
+  }
+  checkLabelsStructure(ctx.body, allIds, findings);
   walkElements(ctx.body, ctx, (el) => {
     const tag = el.rawTagName?.toLowerCase();
-    if (!tag)
-      return;
+    if (!tag) return;
     if (tag === "img") {
       const alt = el.getAttribute?.("alt");
       if (alt === void 0 || alt === null) {
-        findings.push({
+        pushFinding(findings, {
           severity: "error",
           message: "Image missing alt attribute (WCAG 1.1.1)",
           suggestion: 'Add an alt attribute. Use descriptive text for informative images, or alt="" for purely decorative images.',
@@ -126,15 +161,14 @@ const validate = (ctx) => {
     }
     if (tag === "input") {
       const type = (el.getAttribute?.("type") || "text").toLowerCase();
-      if (type === "hidden" || type === "submit" || type === "button" || type === "reset") {
+      if (IGNORED_INPUT_TYPES.has(type)) {
         return;
       }
-      if (!LABELABLE_INPUTS.has(type))
-        return;
-      checkLabel(el, tag, findings, labelForIds);
+      if (!LABELABLE_INPUTS.has(type)) return;
+      checkLabel(el, tag, findings, labelForIds, allIds);
     }
     if (tag === "select" || tag === "textarea") {
-      checkLabel(el, tag, findings, labelForIds);
+      checkLabel(el, tag, findings, labelForIds, allIds);
     }
     if (tag === "button") {
       const text = el.textContent?.trim();
@@ -142,7 +176,7 @@ const validate = (ctx) => {
       const ariaLabelledBy = el.getAttribute?.("aria-labelledby");
       const hasImg = el.querySelector?.("img[alt]");
       if (!text && !ariaLabel && !ariaLabelledBy && !hasImg) {
-        findings.push({
+        pushFinding(findings, {
           severity: "error",
           message: "Button has no accessible name (WCAG 4.1.2)",
           suggestion: "Add text content, an aria-label, or an aria-labelledby attribute to the button.",
@@ -155,7 +189,7 @@ const validate = (ctx) => {
       if (tabindex !== void 0 && tabindex !== null) {
         const val = parseInt(tabindex, 10);
         if (!isNaN(val) && val > 0) {
-          findings.push({
+          pushFinding(findings, {
             severity: "warning",
             message: `Positive tabindex="${tabindex}" disrupts natural tab order (WCAG 2.4.3)`,
             suggestion: 'Use tabindex="0" to add to natural tab order, or tabindex="-1" for programmatic focus. Avoid positive values — they override the DOM order and confuse keyboard users.',
@@ -170,7 +204,7 @@ const validate = (ctx) => {
       if (autoplay !== void 0 && autoplay !== null) {
         const muted = el.getAttribute?.("muted");
         if (muted === void 0 || muted === null) {
-          findings.push({
+          pushFinding(findings, {
             severity: "error",
             message: `<${tag}> has autoplay without muted (WCAG 1.4.2)`,
             suggestion: `Add the muted attribute to <${tag} autoplay>, or remove autoplay. Autoplaying audio is disruptive to screen reader users.`,
@@ -183,7 +217,7 @@ const validate = (ctx) => {
     const role = el.getAttribute?.("role");
     if (role !== void 0 && role !== null) {
       if (!VALID_ARIA_ROLES.has(role)) {
-        findings.push({
+        pushFinding(findings, {
           severity: "error",
           message: `Invalid ARIA role="${role}" (WCAG 4.1.2)`,
           suggestion: `"${role}" is not a valid WAI-ARIA role. Use a valid role such as "button", "link", "navigation", "dialog", etc.`,
@@ -197,7 +231,7 @@ const validate = (ctx) => {
       if (tabindex !== void 0 && tabindex !== null) {
         const val = parseInt(tabindex, 10);
         if (!isNaN(val) && val >= 0 && !role) {
-          findings.push({
+          pushFinding(findings, {
             severity: "warning",
             message: `<${tag}> is focusable via tabindex but has no role (WCAG 4.1.2)`,
             suggestion: `Add a role attribute to indicate the element's purpose to screen readers. Example: <div tabindex="0" role="button"> or <span tabindex="0" role="link">.`,
@@ -209,12 +243,13 @@ const validate = (ctx) => {
     }
   });
   checkDuplicateAdjacentText(ctx.body, findings);
+  checkNestedInteractive(ctx.body, findings);
   if (ctx.head) {
     const viewport = ctx.head.meta.find((m) => m.name?.toLowerCase() === "viewport");
     if (viewport) {
       const content = viewport.content.map((p) => p.value).join("").toLowerCase();
       if (/user-scalable\s*=\s*no/.test(content)) {
-        findings.push({
+        pushFinding(findings, {
           severity: "error",
           message: "Viewport meta disables user scaling (WCAG 1.4.4)",
           suggestion: "Remove user-scalable=no from the viewport meta tag. Users must be able to zoom to at least 200%.",
@@ -224,7 +259,7 @@ const validate = (ctx) => {
       }
       const maxScaleMatch = content.match(/maximum-scale\s*=\s*([\d.]+)/);
       if (maxScaleMatch && parseFloat(maxScaleMatch[1]) < 2) {
-        findings.push({
+        pushFinding(findings, {
           severity: "error",
           message: `Viewport meta restricts zoom to ${maxScaleMatch[1]}x (WCAG 1.4.4)`,
           suggestion: "Set maximum-scale to at least 2, or remove it entirely. Users must be able to zoom to at least 200%.",
@@ -236,21 +271,57 @@ const validate = (ctx) => {
   }
   return findings;
 };
-function checkLabel(el, tag, findings, labelForIds) {
+function checkLabel(el, tag, findings, labelForIds, allIds) {
   const id = el.getAttribute?.("id");
   const ariaLabel = el.getAttribute?.("aria-label");
   const ariaLabelledBy = el.getAttribute?.("aria-labelledby");
-  if (ariaLabel || ariaLabelledBy)
-    return;
-  if (id && labelForIds.has(id))
-    return;
+  let hasAccessibleName = false;
+  if (ariaLabel !== void 0 && ariaLabel !== null) {
+    if (!String(ariaLabel).trim()) {
+      pushFinding(findings, {
+        severity: "error",
+        message: `<${tag}> has empty aria-label (WCAG 4.1.2)`,
+        suggestion: "Provide a non-empty aria-label, use aria-labelledby with an existing id, or associate a <label>.",
+        element: `<${tag}>`,
+        attribute: "aria-label"
+      });
+    } else {
+      hasAccessibleName = true;
+    }
+  }
+  if (ariaLabelledBy !== void 0 && ariaLabelledBy !== null) {
+    const tokens = String(ariaLabelledBy).trim().split(/\s+/).filter(Boolean);
+    if (tokens.length === 0) {
+      pushFinding(findings, {
+        severity: "error",
+        message: `<${tag}> has empty aria-labelledby (WCAG 4.1.2)`,
+        suggestion: "Set aria-labelledby to one or more element ids that exist in this file, or use a non-empty aria-label / <label>.",
+        element: `<${tag}>`,
+        attribute: "aria-labelledby"
+      });
+    } else {
+      const missing = tokens.filter((token) => !allIds.has(token));
+      if (missing.length > 0) {
+        pushFinding(findings, {
+          severity: "error",
+          message: `<${tag}> aria-labelledby references missing id(s): ${missing.join(", ")} (WCAG 1.3.1)`,
+          suggestion: `Add element(s) with id="${missing[0]}" (or fix the aria-labelledby tokens), or use a <label for="..."> / non-empty aria-label instead.`,
+          element: `<${tag}>`,
+          attribute: "aria-labelledby"
+        });
+      } else {
+        hasAccessibleName = true;
+      }
+    }
+  }
+  if (hasAccessibleName) return;
+  if (id && labelForIds.has(id)) return;
   let parent = el.parentNode;
   while (parent) {
-    if (parent.rawTagName?.toLowerCase() === "label")
-      return;
+    if (parent.rawTagName?.toLowerCase() === "label") return;
     parent = parent.parentNode;
   }
-  findings.push({
+  pushFinding(findings, {
     severity: "error",
     message: `<${tag}> has no associated label (WCAG 1.3.1)`,
     suggestion: `Add a <label for="${id || "inputId"}"> that references this ${tag}'s id, wrap it in a <label>, or add an aria-label attribute.`,
@@ -258,20 +329,112 @@ function checkLabel(el, tag, findings, labelForIds) {
     attribute: "id"
   });
 }
-function collectLabelForIds(el, ids) {
+function collectDomIndex(el, labelForIds, allIds, idCounts) {
+  const id = el.getAttribute?.("id");
+  if (id) {
+    allIds.add(id);
+    idCounts.set(id, (idCounts.get(id) ?? 0) + 1);
+  }
   if (el.rawTagName?.toLowerCase() === "label") {
     const forId = el.getAttribute?.("for");
-    if (forId)
-      ids.add(forId);
+    if (forId) labelForIds.add(forId);
   }
   for (const child of el.childNodes ?? []) {
-    if (child.nodeType === 1)
-      collectLabelForIds(child, ids);
+    if (child.nodeType === 1) collectDomIndex(child, labelForIds, allIds, idCounts);
+  }
+}
+function isLabelableControl(el) {
+  const tag = el.rawTagName?.toLowerCase();
+  if (tag === "select" || tag === "textarea") return true;
+  if (tag !== "input") return false;
+  const type = (el.getAttribute?.("type") || "text").toLowerCase();
+  if (IGNORED_INPUT_TYPES.has(type)) return false;
+  return LABELABLE_INPUTS.has(type);
+}
+function countLabelableDescendants(el) {
+  let count = 0;
+  for (const child of el.childNodes ?? []) {
+    if (child.nodeType !== 1) continue;
+    if (isLabelableControl(child)) count += 1;
+    count += countLabelableDescendants(child);
+  }
+  return count;
+}
+function checkLabelsStructure(root, allIds, findings) {
+  function walk(el) {
+    if (el.rawTagName?.toLowerCase() === "label") {
+      const forId = el.getAttribute?.("for");
+      if (forId && !allIds.has(forId)) {
+        pushFinding(findings, {
+          severity: "warning",
+          message: `<label for="${forId}"> has no matching id in this file (WCAG 1.3.1)`,
+          suggestion: `Add id="${forId}" to the related form control, or fix the for attribute.`,
+          element: "<label>",
+          attribute: "for"
+        });
+      }
+      const controlCount = countLabelableDescendants(el);
+      if (controlCount > 1) {
+        pushFinding(findings, {
+          severity: "warning",
+          message: `<label> contains ${controlCount} form controls — screen readers only associate the first (WCAG 1.3.1)`,
+          suggestion: 'Use a separate <label for="id"> for each input (or one wrapping label per control). multiple form controls inside one label is not reliable.',
+          element: "<label>"
+        });
+      }
+    }
+    for (const child of el.childNodes ?? []) {
+      if (child.nodeType === 1) walk(child);
+    }
+  }
+  walk(root);
+}
+function hasHref(el) {
+  const href = el.getAttribute?.("href");
+  return href !== void 0 && href !== null;
+}
+function isInteractiveContainer(el) {
+  const role = el.getAttribute?.("role")?.toLowerCase();
+  if (role) return INTERACTIVE_CONTAINER_ROLES.has(role);
+  const tag = el.rawTagName?.toLowerCase();
+  if (tag === "button") return true;
+  if (tag === "a") return hasHref(el);
+  return false;
+}
+function isFocusable(el) {
+  const role = el.getAttribute?.("role")?.toLowerCase();
+  if (role && WIDGET_ROLES.has(role)) return true;
+  const tag = el.rawTagName?.toLowerCase();
+  if (tag === "a") return hasHref(el);
+  if (tag === "input") return (el.getAttribute?.("type") || "text").toLowerCase() !== "hidden";
+  if (tag && FOCUSABLE_ELEMENTS.has(tag)) return true;
+  const tabindex = el.getAttribute?.("tabindex");
+  if (tabindex !== void 0 && tabindex !== null) {
+    const val = parseInt(tabindex, 10);
+    if (!isNaN(val) && val >= 0) return true;
+  }
+  return false;
+}
+function checkNestedInteractive(root, findings) {
+  function walk(el, ancestorTag) {
+    const tag = el.rawTagName?.toLowerCase();
+    if (tag && ancestorTag && isFocusable(el)) {
+      pushFinding(findings, {
+        severity: "error",
+        message: `Interactive <${tag}> is nested inside <${ancestorTag}> (WCAG 4.1.2)`,
+        suggestion: `Interactive elements cannot be nested — browsers restructure the DOM and screen readers announce an ambiguous control. Move the <${tag}> outside the <${ancestorTag}>, or make the outer element a non-interactive container such as <div>.`,
+        element: `<${tag}>`
+      });
+    }
+    const childAncestor = isInteractiveContainer(el) ? tag ?? ancestorTag : ancestorTag;
+    for (const child of el.childNodes ?? []) {
+      if (child.nodeType === 1) walk(child, childAncestor);
+    }
   }
+  walk(root, void 0);
 }
 function getVisibleText(el) {
-  if (el.getAttribute?.("aria-hidden") === "true")
-    return "";
+  if (el.getAttribute?.("aria-hidden") === "true") return "";
   return (el.textContent ?? "").trim().replace(/\s+/g, " ");
 }
 function checkDuplicateAdjacentText(root, findings) {
@@ -284,7 +447,7 @@ function checkDuplicateAdjacentText(root, findings) {
       const nextText = getVisibleText(next);
       if (currentText && nextText && currentText === nextText && current.getAttribute?.("aria-hidden") !== "true" && next.getAttribute?.("aria-hidden") !== "true") {
         const tag = next.rawTagName?.toLowerCase() || "element";
-        findings.push({
+        pushFinding(findings, {
           severity: "warning",
           message: `Adjacent <${current.rawTagName?.toLowerCase()}> and <${tag}> have identical text "${currentText.slice(0, 40)}${currentText.length > 40 ? "..." : ""}" — screen readers will announce it twice`,
           suggestion: 'Add aria-hidden="true" to the decorative duplicate. If both are meaningful, differentiate their text content.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/a11y-validator",
-  "version": "0.22.2",
+  "version": "0.23.1",
   "type": "module",
   "description": "Accessibility validation plugin for Jay Framework — checks jay-html templates for WCAG best practices",
   "license": "Apache-2.0",
@@ -24,11 +24,11 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@jay-framework/compiler-shared": "^0.22.2"
+    "@jay-framework/compiler-shared": "^0.23.1"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.22.2",
-    "@jay-framework/jay-stack-cli": "^0.22.2",
+    "@jay-framework/dev-environment": "^0.23.1",
+    "@jay-framework/jay-stack-cli": "^0.23.1",
     "@types/node": "^22.15.21",
     "node-html-parser": "^6.1.0",
     "rimraf": "^5.0.5",