@jay-framework/a11y-validator 0.19.0

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { JayHtmlValidatorFn } from '@jay-framework/compiler-shared';
+
+declare const validate: JayHtmlValidatorFn;
+
+export { validate };

package/dist/index.js

@@ -0,0 +1,254 @@
+import { walkElements } from "@jay-framework/compiler-shared";
+const INTERACTIVE_ELEMENTS = /* @__PURE__ */ new Set([
+  "a",
+  "button",
+  "input",
+  "select",
+  "textarea"
+]);
+const NON_INTERACTIVE_ELEMENTS = /* @__PURE__ */ new Set([
+  "div",
+  "span",
+  "p",
+  "section",
+  "article",
+  "header",
+  "footer",
+  "main",
+  "nav",
+  "aside",
+  "li",
+  "ul",
+  "ol"
+]);
+const VALID_ARIA_ROLES = /* @__PURE__ */ new Set([
+  "alert",
+  "alertdialog",
+  "application",
+  "article",
+  "banner",
+  "button",
+  "cell",
+  "checkbox",
+  "columnheader",
+  "combobox",
+  "complementary",
+  "contentinfo",
+  "definition",
+  "dialog",
+  "directory",
+  "document",
+  "feed",
+  "figure",
+  "form",
+  "grid",
+  "gridcell",
+  "group",
+  "heading",
+  "img",
+  "link",
+  "list",
+  "listbox",
+  "listitem",
+  "log",
+  "main",
+  "marquee",
+  "math",
+  "menu",
+  "menubar",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "meter",
+  "navigation",
+  "none",
+  "note",
+  "option",
+  "presentation",
+  "progressbar",
+  "radio",
+  "radiogroup",
+  "region",
+  "row",
+  "rowgroup",
+  "rowheader",
+  "scrollbar",
+  "search",
+  "searchbox",
+  "separator",
+  "slider",
+  "spinbutton",
+  "status",
+  "switch",
+  "tab",
+  "table",
+  "tablist",
+  "tabpanel",
+  "term",
+  "textbox",
+  "timer",
+  "toolbar",
+  "tooltip",
+  "tree",
+  "treegrid",
+  "treeitem"
+]);
+const LABELABLE_INPUTS = /* @__PURE__ */ new Set([
+  "text",
+  "password",
+  "email",
+  "tel",
+  "url",
+  "number",
+  "search",
+  "date",
+  "time",
+  "datetime-local",
+  "month",
+  "week",
+  "color",
+  "file",
+  "range"
+]);
+const validate = (ctx) => {
+  const findings = [];
+  const labelForIds = /* @__PURE__ */ new Set();
+  collectLabelForIds(ctx.body, labelForIds);
+  walkElements(ctx.body, ctx, (el) => {
+    const tag = el.rawTagName?.toLowerCase();
+    if (!tag)
+      return;
+    if (tag === "img") {
+      const alt = el.getAttribute?.("alt");
+      if (alt === void 0 || alt === null) {
+        findings.push({
+          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.',
+          element: "<img>",
+          attribute: "alt"
+        });
+      }
+    }
+    if (tag === "input") {
+      const type = (el.getAttribute?.("type") || "text").toLowerCase();
+      if (type === "hidden" || type === "submit" || type === "button" || type === "reset") {
+        return;
+      }
+      if (!LABELABLE_INPUTS.has(type))
+        return;
+      checkLabel(el, tag, findings, labelForIds);
+    }
+    if (tag === "select" || tag === "textarea") {
+      checkLabel(el, tag, findings, labelForIds);
+    }
+    if (tag === "button") {
+      const text = el.textContent?.trim();
+      const ariaLabel = el.getAttribute?.("aria-label");
+      const ariaLabelledBy = el.getAttribute?.("aria-labelledby");
+      const hasImg = el.querySelector?.("img[alt]");
+      if (!text && !ariaLabel && !ariaLabelledBy && !hasImg) {
+        findings.push({
+          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.",
+          element: "<button>"
+        });
+      }
+    }
+    if (INTERACTIVE_ELEMENTS.has(tag) || el.getAttribute?.("role")) {
+      const tabindex = el.getAttribute?.("tabindex");
+      if (tabindex !== void 0 && tabindex !== null) {
+        const val = parseInt(tabindex, 10);
+        if (!isNaN(val) && val > 0) {
+          findings.push({
+            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.',
+            element: `<${tag}>`,
+            attribute: "tabindex"
+          });
+        }
+      }
+    }
+    if (tag === "video" || tag === "audio") {
+      const autoplay = el.getAttribute?.("autoplay");
+      if (autoplay !== void 0 && autoplay !== null) {
+        const muted = el.getAttribute?.("muted");
+        if (muted === void 0 || muted === null) {
+          findings.push({
+            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.`,
+            element: `<${tag}>`,
+            attribute: "autoplay"
+          });
+        }
+      }
+    }
+    const role = el.getAttribute?.("role");
+    if (role !== void 0 && role !== null) {
+      if (!VALID_ARIA_ROLES.has(role)) {
+        findings.push({
+          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.`,
+          element: `<${tag}>`,
+          attribute: "role"
+        });
+      }
+    }
+    if (NON_INTERACTIVE_ELEMENTS.has(tag)) {
+      const tabindex = el.getAttribute?.("tabindex");
+      if (tabindex !== void 0 && tabindex !== null) {
+        const val = parseInt(tabindex, 10);
+        if (!isNaN(val) && val >= 0 && !role) {
+          findings.push({
+            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">.`,
+            element: `<${tag}>`,
+            attribute: "role"
+          });
+        }
+      }
+    }
+  });
+  return findings;
+};
+function checkLabel(el, tag, findings, labelForIds) {
+  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 parent = el.parentNode;
+  while (parent) {
+    if (parent.rawTagName?.toLowerCase() === "label")
+      return;
+    parent = parent.parentNode;
+  }
+  findings.push({
+    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.`,
+    element: `<${tag}>`,
+    attribute: "id"
+  });
+}
+function collectLabelForIds(el, ids) {
+  if (el.rawTagName?.toLowerCase() === "label") {
+    const forId = el.getAttribute?.("for");
+    if (forId)
+      ids.add(forId);
+  }
+  for (const child of el.childNodes ?? []) {
+    if (child.nodeType === 1)
+      collectLabelForIds(child, ids);
+  }
+}
+export {
+  validate
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@jay-framework/a11y-validator",
+  "version": "0.19.0",
+  "type": "module",
+  "description": "Accessibility validation plugin for Jay Framework — checks jay-html templates for WCAG best practices",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "plugin.yaml"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./plugin.yaml": "./plugin.yaml"
+  },
+  "scripts": {
+    "build": "npm run clean && npm run build:server && npm run build:types && npm run validate",
+    "validate": "jay-stack-cli validate-plugin",
+    "build:server": "vite build --ssr",
+    "build:types": "tsup lib/index.ts --dts-only --format esm",
+    "build:check-types": "tsc",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run test",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@jay-framework/compiler-shared": "^0.19.0"
+  },
+  "devDependencies": {
+    "@jay-framework/dev-environment": "^0.19.0",
+    "@jay-framework/jay-stack-cli": "^0.19.0",
+    "@types/node": "^22.15.21",
+    "node-html-parser": "^6.1.0",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11",
+    "vitest": "^1.2.1"
+  }
+}

package/plugin.yaml

@@ -0,0 +1,6 @@
+name: a11y-validator
+
+validators:
+  - name: accessibility
+    handler: validate
+    description: Validates jay-html templates for WCAG accessibility best practices