@a13y/devtools 0.1.0

package/dist/runtime/index.js

@@ -0,0 +1,1510 @@
+import { isDevelopment } from '@a13y/core/runtime/env';
+
+// @a13y/devtools - Development-time validators (tree-shakeable in production)
+
+
+// src/runtime/warnings/warning-system.ts
+var Styles = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  blue: "\x1B[34m",
+  cyan: "\x1B[36m",
+  gray: "\x1B[90m",
+  // Backgrounds
+  bgRed: "\x1B[41m",
+  bgYellow: "\x1B[43m",
+  bgBlue: "\x1B[44m"
+};
+var style = (text, ...styles) => {
+  return `${styles.join("")}${text}${Styles.reset}`;
+};
+var WarningSystemClass = class {
+  constructor() {
+    this.config = {
+      enabled: true,
+      minSeverity: "warn",
+      showElement: true,
+      showStackTrace: true,
+      deduplicate: true,
+      onWarning: () => {
+      }
+    };
+    this.warningCache = /* @__PURE__ */ new Set();
+  }
+  /**
+   * Configure the warning system
+   */
+  configure(config) {
+    this.config = { ...this.config, ...config };
+  }
+  /**
+   * Emit a warning
+   */
+  warn(warning) {
+    if (!this.config.enabled) {
+      return;
+    }
+    const severityLevel = { info: 0, warn: 1, error: 2 };
+    if (severityLevel[warning.severity] < severityLevel[this.config.minSeverity]) {
+      return;
+    }
+    if (this.config.deduplicate) {
+      const key = this.getWarningKey(warning);
+      if (this.warningCache.has(key)) {
+        return;
+      }
+      this.warningCache.add(key);
+    }
+    if (this.config.onWarning) {
+      this.config.onWarning(warning);
+    }
+    this.printWarning(warning);
+  }
+  /**
+   * Clear warning cache
+   */
+  clearCache() {
+    this.warningCache.clear();
+  }
+  /**
+   * Generate a unique key for a warning
+   */
+  getWarningKey(warning) {
+    const parts = [warning.code, warning.message];
+    if (warning.element) {
+      const tag = warning.element.tagName.toLowerCase();
+      const id = warning.element.id;
+      const classes = Array.from(warning.element.classList).join(".");
+      parts.push(`${tag}#${id}.${classes}`);
+    }
+    return parts.join("|");
+  }
+  /**
+   * Print warning to console
+   */
+  printWarning(warning) {
+    const { severity, code, category, message, element, wcag, fixes } = warning;
+    const badge = this.getSeverityBadge(severity);
+    console.group(
+      `${badge} ${style(code, Styles.bold, Styles.cyan)} ${style(category, Styles.dim)}`
+    );
+    console.log(style(message, Styles.bold));
+    if (element && this.config.showElement) {
+      console.log(style("\nElement:", Styles.bold));
+      console.log(element);
+    }
+    if (wcag) {
+      console.log(style("\nWCAG:", Styles.bold), `${wcag.criterion} (Level ${wcag.level})`);
+      console.log(style("Learn more:", Styles.blue), wcag.url);
+    }
+    if (fixes.length > 0) {
+      console.log(style("\nHow to fix:", Styles.bold, Styles.cyan));
+      fixes.forEach((fix, index) => {
+        console.log(`${index + 1}. ${fix.description}`);
+        if (fix.example) {
+          console.log(style("\n   Example:", Styles.dim));
+          console.log(style(`   ${fix.example}`, Styles.dim, Styles.gray));
+        }
+        if (fix.learnMoreUrl) {
+          console.log(style("   Learn more:", Styles.blue), fix.learnMoreUrl);
+        }
+      });
+    }
+    if (severity === "error" && this.config.showStackTrace) {
+      console.log(style("\nStack trace:", Styles.dim));
+      console.trace();
+    }
+    console.groupEnd();
+    console.log("");
+  }
+  /**
+   * Get severity badge for console
+   */
+  getSeverityBadge(severity) {
+    switch (severity) {
+      case "error":
+        return style(" ERROR ", Styles.bold, Styles.bgRed);
+      case "warn":
+        return style(" WARN ", Styles.bold, Styles.bgYellow);
+      case "info":
+        return style(" INFO ", Styles.bold, Styles.bgBlue);
+    }
+  }
+};
+var WarningSystem = new WarningSystemClass();
+var createWarning = (partial) => {
+  return {
+    fixes: [],
+    ...partial
+  };
+};
+
+// src/runtime/warnings/warning-types.ts
+var WarningCodes = {
+  // Focus Management (001-099)
+  FOCUS_LOST: "A13Y001",
+  FOCUS_NOT_VISIBLE: "A13Y002",
+  FOCUS_TRAP_BROKEN: "A13Y003",
+  FOCUS_ORDER_INVALID: "A13Y004",
+  FOCUS_NOT_RESTORED: "A13Y005",
+  // Keyboard Navigation (100-199)
+  NOT_KEYBOARD_ACCESSIBLE: "A13Y100",
+  MISSING_KEYBOARD_HANDLER: "A13Y101",
+  INVALID_TABINDEX: "A13Y102",
+  ROVING_TABINDEX_BROKEN: "A13Y103",
+  MISSING_ESC_HANDLER: "A13Y104",
+  // Accessible Name (200-299)
+  MISSING_ACCESSIBLE_NAME: "A13Y200",
+  EMPTY_ACCESSIBLE_NAME: "A13Y201",
+  DUPLICATE_ID: "A13Y202",
+  INVALID_LABELLEDBY: "A13Y203",
+  PLACEHOLDER_AS_LABEL: "A13Y204",
+  // ARIA Usage (300-399)
+  INVALID_ARIA_ROLE: "A13Y300",
+  INVALID_ARIA_ATTRIBUTE: "A13Y301",
+  CONFLICTING_ARIA: "A13Y302",
+  REDUNDANT_ARIA: "A13Y303",
+  MISSING_REQUIRED_ARIA: "A13Y304",
+  INVALID_ARIA_VALUE: "A13Y305",
+  // Semantic HTML (400-499)
+  DIV_BUTTON: "A13Y400",
+  DIV_LINK: "A13Y401",
+  MISSING_LANDMARK: "A13Y402",
+  INVALID_NESTING: "A13Y403",
+  // WCAG Compliance (500-599)
+  CONTRAST_INSUFFICIENT: "A13Y500",
+  TARGET_SIZE_TOO_SMALL: "A13Y501",
+  ANIMATION_NO_REDUCE_MOTION: "A13Y502",
+  // Performance (600-699)
+  TOO_MANY_LIVE_REGIONS: "A13Y600",
+  EXCESSIVE_ANNOUNCEMENTS: "A13Y601"
+};
+var WCAGUrls = {
+  "1.3.1": "https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html",
+  "1.4.3": "https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html",
+  "2.1.1": "https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html",
+  "2.1.2": "https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html",
+  "2.4.3": "https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html",
+  "2.4.7": "https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html",
+  "2.5.5": "https://www.w3.org/WAI/WCAG22/Understanding/target-size.html",
+  "4.1.2": "https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html",
+  "4.1.3": "https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html"
+};
+
+// src/runtime/invariants/invariants.ts
+var invariant = (condition, message) => {
+  if (!isDevelopment()) {
+    return;
+  }
+  if (!condition) {
+    throw new Error(`[@a13y/devtools] Invariant violation: ${message}`);
+  }
+};
+var assertHasAccessibleName = (element, context) => {
+  if (!isDevelopment()) {
+    return;
+  }
+  import('@a13y/core/runtime/aria').then(({ getAccessibleName }) => {
+    const name = getAccessibleName(element);
+    if (!name || name.trim().length === 0) {
+      WarningSystem.warn(
+        createWarning({
+          code: WarningCodes.MISSING_ACCESSIBLE_NAME,
+          severity: "error",
+          category: "accessible-name",
+          message: `Element is missing an accessible name${context ? ` in ${context}` : ""}`,
+          element,
+          wcag: {
+            criterion: "4.1.2",
+            level: "A",
+            url: WCAGUrls["4.1.2"]
+          },
+          fixes: [
+            {
+              description: "Add an aria-label attribute",
+              example: `<${element.tagName.toLowerCase()} aria-label="Descriptive name">`
+            },
+            {
+              description: "Add text content",
+              example: `<${element.tagName.toLowerCase()}>Click me</${element.tagName.toLowerCase()}>`
+            },
+            {
+              description: "Use aria-labelledby to reference another element",
+              example: `<${element.tagName.toLowerCase()} aria-labelledby="label-id">`
+            }
+          ]
+        })
+      );
+    }
+  }).catch(() => {
+  });
+};
+var assertKeyboardAccessible = (element, context) => {
+  if (!isDevelopment()) {
+    return;
+  }
+  const isButton = element instanceof HTMLButtonElement;
+  const isLink = element instanceof HTMLAnchorElement && element.hasAttribute("href");
+  const isInput = element instanceof HTMLInputElement;
+  const hasTabindex = element.hasAttribute("tabindex");
+  const tabindex = hasTabindex ? parseInt(element.getAttribute("tabindex") || "0", 10) : -1;
+  const isAccessible = isButton || isLink || isInput || hasTabindex && tabindex >= 0;
+  if (!isAccessible) {
+    WarningSystem.warn(
+      createWarning({
+        code: WarningCodes.NOT_KEYBOARD_ACCESSIBLE,
+        severity: "error",
+        category: "keyboard-navigation",
+        message: `Element is not keyboard accessible${context ? ` in ${context}` : ""}`,
+        element,
+        wcag: {
+          criterion: "2.1.1",
+          level: "A",
+          url: WCAGUrls["2.1.1"]
+        },
+        fixes: [
+          {
+            description: "Use a semantic HTML element (button, a, input)",
+            example: `<button type="button">Click me</button>`
+          },
+          {
+            description: 'Add tabindex="0" to make it focusable',
+            example: `<${element.tagName.toLowerCase()} tabindex="0">`
+          },
+          {
+            description: "Add keyboard event handlers (Enter, Space)",
+            example: `element.addEventListener('keydown', (e) => {
+  if (e.key === 'Enter' || e.key === ' ') {
+    e.preventDefault();
+    // Handle activation
+  }
+});`
+          }
+        ]
+      })
+    );
+  }
+  const hasClickHandler = element.getAttribute("onclick") !== null;
+  if (hasClickHandler && !isButton && !isLink) {
+    WarningSystem.warn(
+      createWarning({
+        code: WarningCodes.MISSING_KEYBOARD_HANDLER,
+        severity: "warn",
+        category: "keyboard-navigation",
+        message: `Element has click handler but no keyboard handlers${context ? ` in ${context}` : ""}`,
+        element,
+        wcag: {
+          criterion: "2.1.1",
+          level: "A",
+          url: WCAGUrls["2.1.1"]
+        },
+        fixes: [
+          {
+            description: "Add onKeyDown handler for Enter and Space keys",
+            example: `const handleKeyDown = (e: KeyboardEvent) => {
+  if (e.key === 'Enter' || e.key === ' ') {
+    e.preventDefault();
+    onClick(e);
+  }
+};`
+          }
+        ]
+      })
+    );
+  }
+};
+var assertValidTabindex = (element) => {
+  if (!isDevelopment()) {
+    return;
+  }
+  const tabindex = element.getAttribute("tabindex");
+  if (tabindex === null) {
+    return;
+  }
+  const value = parseInt(tabindex, 10);
+  if (value > 0) {
+    WarningSystem.warn(
+      createWarning({
+        code: WarningCodes.INVALID_TABINDEX,
+        severity: "warn",
+        category: "keyboard-navigation",
+        message: `Positive tabindex (${value}) creates confusing tab order`,
+        element,
+        wcag: {
+          criterion: "2.4.3",
+          level: "A",
+          url: WCAGUrls["2.4.3"]
+        },
+        fixes: [
+          {
+            description: 'Use tabindex="0" to add element to natural tab order',
+            example: `<div tabindex="0">Focusable in natural order</div>`
+          },
+          {
+            description: 'Use tabindex="-1" to remove from tab order (programmatic focus only)',
+            example: `<div tabindex="-1">Not in tab order</div>`
+          },
+          {
+            description: "Restructure DOM to achieve desired focus order",
+            learnMoreUrl: "https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html"
+          }
+        ]
+      })
+    );
+  }
+};
+var assertValidAriaAttributes = (element) => {
+  if (!isDevelopment()) {
+    return;
+  }
+  const role = element.getAttribute("role");
+  const ariaAttributes = Array.from(element.attributes).filter(
+    (attr) => attr.name.startsWith("aria-")
+  );
+  if (!role && ariaAttributes.length > 0 && !isSemanticElement(element)) {
+    WarningSystem.warn(
+      createWarning({
+        code: WarningCodes.MISSING_REQUIRED_ARIA,
+        severity: "warn",
+        category: "aria-usage",
+        message: "Element has ARIA attributes but no explicit role",
+        element,
+        wcag: {
+          criterion: "4.1.2",
+          level: "A",
+          url: WCAGUrls["4.1.2"]
+        },
+        fixes: [
+          {
+            description: "Add an appropriate role attribute",
+            example: `<div role="button" aria-pressed="false">Toggle</div>`
+          },
+          {
+            description: "Use a semantic HTML element instead",
+            example: `<button aria-pressed="false">Toggle</button>`
+          }
+        ]
+      })
+    );
+  }
+  if (role && isSemanticElement(element)) {
+    const semanticRole = getImplicitRole(element);
+    if (role === semanticRole) {
+      WarningSystem.warn(
+        createWarning({
+          code: WarningCodes.REDUNDANT_ARIA,
+          severity: "info",
+          category: "aria-usage",
+          message: `Role "${role}" is redundant on <${element.tagName.toLowerCase()}>`,
+          element,
+          fixes: [
+            {
+              description: "Remove the redundant role attribute",
+              example: `<${element.tagName.toLowerCase()}> (role="${role}" is implicit)`
+            }
+          ]
+        })
+      );
+    }
+  }
+};
+var assertFocusVisible = (context) => {
+  if (!isDevelopment()) {
+    return;
+  }
+  setTimeout(() => {
+    const activeElement = document.activeElement;
+    if (!activeElement || activeElement === document.body) {
+      WarningSystem.warn(
+        createWarning({
+          code: WarningCodes.FOCUS_LOST,
+          severity: "warn",
+          category: "focus-management",
+          message: `Focus was lost${context ? ` after ${context}` : ""}`,
+          wcag: {
+            criterion: "2.4.3",
+            level: "A",
+            url: WCAGUrls["2.4.3"]
+          },
+          fixes: [
+            {
+              description: "Ensure focus is moved to an appropriate element",
+              example: `// After closing dialog
+const returnElement = document.getElementById('trigger-button');
+returnElement?.focus();`
+            },
+            {
+              description: "Use FocusManager to save and restore focus",
+              example: `import { FocusManager } from '@a13y/core/runtime/focus';
+
+const restore = FocusManager.saveFocus();
+// ... perform action ...
+restore();`
+            }
+          ]
+        })
+      );
+    }
+  }, 100);
+};
+var isSemanticElement = (element) => {
+  const tag = element.tagName.toLowerCase();
+  const semanticTags = [
+    "button",
+    "a",
+    "input",
+    "select",
+    "textarea",
+    "nav",
+    "main",
+    "article",
+    "section",
+    "header",
+    "footer",
+    "aside"
+  ];
+  return semanticTags.includes(tag);
+};
+var getImplicitRole = (element) => {
+  const tag = element.tagName.toLowerCase();
+  const roleMap = {
+    button: "button",
+    a: "link",
+    nav: "navigation",
+    main: "main",
+    article: "article",
+    section: "region",
+    header: "banner",
+    footer: "contentinfo",
+    aside: "complementary"
+  };
+  return roleMap[tag] || null;
+};
+var VALID_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",
+  "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"
+]);
+var REQUIRED_ARIA_PROPS = {
+  checkbox: ["aria-checked"],
+  combobox: ["aria-expanded", "aria-controls"],
+  gridcell: ["aria-colindex"],
+  heading: ["aria-level"],
+  listbox: ["aria-orientation"],
+  option: ["aria-selected"],
+  progressbar: ["aria-valuenow", "aria-valuemin", "aria-valuemax"],
+  radio: ["aria-checked"],
+  scrollbar: ["aria-valuenow", "aria-valuemin", "aria-valuemax", "aria-controls"],
+  separator: ["aria-valuenow", "aria-valuemin", "aria-valuemax"],
+  slider: ["aria-valuenow", "aria-valuemin", "aria-valuemax"],
+  spinbutton: ["aria-valuenow", "aria-valuemin", "aria-valuemax"],
+  switch: ["aria-checked"],
+  tab: ["aria-selected"],
+  tabpanel: ["aria-labelledby"],
+  textbox: ["aria-multiline"],
+  treegrid: ["aria-multiselectable"]
+};
+var GLOBAL_ARIA_ATTRS = /* @__PURE__ */ new Set([
+  "aria-atomic",
+  "aria-busy",
+  "aria-controls",
+  "aria-current",
+  "aria-describedby",
+  "aria-details",
+  "aria-disabled",
+  "aria-dropeffect",
+  "aria-errormessage",
+  "aria-flowto",
+  "aria-grabbed",
+  "aria-haspopup",
+  "aria-hidden",
+  "aria-invalid",
+  "aria-keyshortcuts",
+  "aria-label",
+  "aria-labelledby",
+  "aria-live",
+  "aria-owns",
+  "aria-relevant",
+  "aria-roledescription"
+]);
+var AriaValidator = class {
+  /**
+   * Validate ARIA attributes on an element
+   */
+  validateElement(element) {
+    if (!isDevelopment()) {
+      return;
+    }
+    const role = element.getAttribute("role");
+    const ariaAttrs = this.getAriaAttributes(element);
+    if (role) {
+      this.validateRole(element, role);
+    }
+    ariaAttrs.forEach((attr) => {
+      this.validateAriaAttribute(element, attr, role);
+    });
+    if (role && REQUIRED_ARIA_PROPS[role]) {
+      this.validateRequiredProps(element, role);
+    }
+    this.checkRedundantAria(element, role);
+    this.checkConflictingAria(element, ariaAttrs);
+  }
+  /**
+   * Validate accessible name
+   */
+  validateAccessibleName(element, context) {
+    if (!isDevelopment()) {
+      return;
+    }
+    import('@a13y/core/runtime/aria').then(({ getAccessibleName }) => {
+      const name = getAccessibleName(element);
+      if (!name || name.trim().length === 0) {
+        WarningSystem.warn(
+          createWarning({
+            code: WarningCodes.MISSING_ACCESSIBLE_NAME,
+            severity: "error",
+            category: "accessible-name",
+            message: `Element is missing an accessible name${context ? ` in ${context}` : ""}`,
+            element,
+            wcag: {
+              criterion: "4.1.2",
+              level: "A",
+              url: WCAGUrls["4.1.2"]
+            },
+            fixes: [
+              {
+                description: "Add aria-label",
+                example: `<${element.tagName.toLowerCase()} aria-label="Description">`
+              },
+              {
+                description: "Add text content",
+                example: `<${element.tagName.toLowerCase()}>Button text</${element.tagName.toLowerCase()}>`
+              },
+              {
+                description: "Use aria-labelledby",
+                example: `<${element.tagName.toLowerCase()} aria-labelledby="label-id">`
+              }
+            ]
+          })
+        );
+      }
+      if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) {
+        const placeholder = element.placeholder;
+        if (placeholder && (!name || name === placeholder)) {
+          WarningSystem.warn(
+            createWarning({
+              code: WarningCodes.PLACEHOLDER_AS_LABEL,
+              severity: "warn",
+              category: "accessible-name",
+              message: "Using placeholder as accessible name is not recommended",
+              element,
+              wcag: {
+                criterion: "4.1.2",
+                level: "A",
+                url: WCAGUrls["4.1.2"]
+              },
+              fixes: [
+                {
+                  description: "Add a visible label",
+                  example: `<label for="input-id">Label text</label>
+<input id="input-id" placeholder="Example">`
+                },
+                {
+                  description: "Add aria-label",
+                  example: `<input aria-label="Label text" placeholder="Example">`
+                }
+              ]
+            })
+          );
+        }
+      }
+    }).catch(() => {
+    });
+  }
+  /**
+   * Validate role attribute
+   */
+  validateRole(element, role) {
+    if (!VALID_ROLES.has(role)) {
+      WarningSystem.warn(
+        createWarning({
+          code: WarningCodes.INVALID_ARIA_ROLE,
+          severity: "error",
+          category: "aria-usage",
+          message: `Invalid ARIA role: "${role}"`,
+          element,
+          wcag: {
+            criterion: "4.1.2",
+            level: "A",
+            url: WCAGUrls["4.1.2"]
+          },
+          fixes: [
+            {
+              description: "Use a valid ARIA role from the specification",
+              learnMoreUrl: "https://www.w3.org/TR/wai-aria-1.2/#role_definitions"
+            },
+            {
+              description: "Remove the role attribute if not needed"
+            }
+          ]
+        })
+      );
+    }
+  }
+  /**
+   * Validate ARIA attribute
+   */
+  validateAriaAttribute(element, attr, role) {
+    if (!attr.startsWith("aria-")) {
+      return;
+    }
+    const value = element.getAttribute(attr);
+    if ([
+      "aria-atomic",
+      "aria-busy",
+      "aria-disabled",
+      "aria-hidden",
+      "aria-multiline",
+      "aria-multiselectable",
+      "aria-readonly",
+      "aria-required"
+    ].includes(attr)) {
+      if (value !== "true" && value !== "false") {
+        WarningSystem.warn(
+          createWarning({
+            code: WarningCodes.INVALID_ARIA_VALUE,
+            severity: "warn",
+            category: "aria-usage",
+            message: `ARIA attribute "${attr}" must be "true" or "false", got "${value}"`,
+            element,
+            wcag: {
+              criterion: "4.1.2",
+              level: "A",
+              url: WCAGUrls["4.1.2"]
+            },
+            fixes: [
+              {
+                description: 'Use "true" or "false"',
+                example: `<element ${attr}="true">`
+              }
+            ]
+          })
+        );
+      }
+    }
+    if (["aria-labelledby", "aria-describedby", "aria-controls", "aria-owns"].includes(attr)) {
+      this.validateIdReferences(element, attr, value);
+    }
+    if (role && !GLOBAL_ARIA_ATTRS.has(attr)) ;
+  }
+  /**
+   * Validate ID references in ARIA attributes
+   */
+  validateIdReferences(element, attr, value) {
+    if (!value) return;
+    const ids = value.split(/\s+/);
+    ids.forEach((id) => {
+      const referencedElement = document.getElementById(id);
+      if (!referencedElement) {
+        WarningSystem.warn(
+          createWarning({
+            code: WarningCodes.INVALID_LABELLEDBY,
+            severity: "warn",
+            category: "aria-usage",
+            message: `${attr} references non-existent element with id="${id}"`,
+            element,
+            wcag: {
+              criterion: "4.1.2",
+              level: "A",
+              url: WCAGUrls["4.1.2"]
+            },
+            fixes: [
+              {
+                description: "Ensure the referenced element exists",
+                example: `<div id="${id}">Label text</div>
+<button ${attr}="${id}">Button</button>`
+              },
+              {
+                description: "Use aria-label instead",
+                example: `<button aria-label="Button text">Button</button>`
+              }
+            ]
+          })
+        );
+      }
+    });
+    const allElements = document.querySelectorAll(`[id]`);
+    const idCounts = /* @__PURE__ */ new Map();
+    allElements.forEach((el) => {
+      const id = el.id;
+      idCounts.set(id, (idCounts.get(id) || 0) + 1);
+    });
+    ids.forEach((id) => {
+      if ((idCounts.get(id) || 0) > 1) {
+        WarningSystem.warn(
+          createWarning({
+            code: WarningCodes.DUPLICATE_ID,
+            severity: "error",
+            category: "aria-usage",
+            message: `Duplicate id="${id}" found in document`,
+            element,
+            wcag: {
+              criterion: "4.1.1",
+              level: "A",
+              url: "https://www.w3.org/WAI/WCAG22/Understanding/parsing.html"
+            },
+            fixes: [
+              {
+                description: "Ensure all IDs are unique",
+                example: `<!-- Make sure each ID is used only once -->
+<div id="unique-id-1">First</div>
+<div id="unique-id-2">Second</div>`
+              }
+            ]
+          })
+        );
+      }
+    });
+  }
+  /**
+   * Validate required ARIA props for a role
+   */
+  validateRequiredProps(element, role) {
+    const requiredProps = REQUIRED_ARIA_PROPS[role] || [];
+    requiredProps.forEach((prop) => {
+      if (!element.hasAttribute(prop)) {
+        WarningSystem.warn(
+          createWarning({
+            code: WarningCodes.MISSING_REQUIRED_ARIA,
+            severity: "error",
+            category: "aria-usage",
+            message: `Role "${role}" requires "${prop}" attribute`,
+            element,
+            wcag: {
+              criterion: "4.1.2",
+              level: "A",
+              url: WCAGUrls["4.1.2"]
+            },
+            fixes: [
+              {
+                description: `Add the required ${prop} attribute`,
+                example: `<${element.tagName.toLowerCase()} role="${role}" ${prop}="value">`,
+                learnMoreUrl: `https://www.w3.org/TR/wai-aria-1.2/#${role}`
+              }
+            ]
+          })
+        );
+      }
+    });
+  }
+  /**
+   * Check for redundant ARIA
+   */
+  checkRedundantAria(element, role) {
+    const tagName = element.tagName.toLowerCase();
+    const implicitRoles = {
+      button: "button",
+      a: "link",
+      nav: "navigation",
+      main: "main",
+      header: "banner",
+      footer: "contentinfo",
+      article: "article",
+      aside: "complementary",
+      section: "region"
+    };
+    if (role && implicitRoles[tagName] === role) {
+      WarningSystem.warn(
+        createWarning({
+          code: WarningCodes.REDUNDANT_ARIA,
+          severity: "info",
+          category: "aria-usage",
+          message: `Role "${role}" is redundant on <${tagName}>`,
+          element,
+          fixes: [
+            {
+              description: "Remove the redundant role attribute",
+              example: `<${tagName}> (role="${role}" is implicit)`
+            }
+          ]
+        })
+      );
+    }
+  }
+  /**
+   * Check for conflicting ARIA attributes
+   */
+  checkConflictingAria(element, ariaAttrs) {
+    if (ariaAttrs.includes("aria-label") && ariaAttrs.includes("aria-labelledby")) {
+      WarningSystem.warn(
+        createWarning({
+          code: WarningCodes.CONFLICTING_ARIA,
+          severity: "warn",
+          category: "aria-usage",
+          message: "Element has both aria-label and aria-labelledby (labelledby takes precedence)",
+          element,
+          fixes: [
+            {
+              description: "Remove aria-label and keep aria-labelledby",
+              example: `<element aria-labelledby="label-id">`
+            },
+            {
+              description: "Remove aria-labelledby and keep aria-label",
+              example: `<element aria-label="Label text">`
+            }
+          ]
+        })
+      );
+    }
+    if (element.getAttribute("aria-hidden") === "true") {
+      const isFocusable = element instanceof HTMLButtonElement || element instanceof HTMLAnchorElement || element instanceof HTMLInputElement || element.hasAttribute("tabindex") && parseInt(element.getAttribute("tabindex") || "0", 10) >= 0;
+      if (isFocusable) {
+        WarningSystem.warn(
+          createWarning({
+            code: WarningCodes.CONFLICTING_ARIA,
+            severity: "error",
+            category: "aria-usage",
+            message: 'Focusable element has aria-hidden="true"',
+            element,
+            wcag: {
+              criterion: "4.1.2",
+              level: "A",
+              url: WCAGUrls["4.1.2"]
+            },
+            fixes: [
+              {
+                description: "Remove aria-hidden",
+                example: `<button>Visible button</button>`
+              },
+              {
+                description: "Make element non-focusable",
+                example: `<div aria-hidden="true" tabindex="-1">Hidden content</div>`
+              }
+            ]
+          })
+        );
+      }
+    }
+  }
+  /**
+   * Get all ARIA attributes from an element
+   */
+  getAriaAttributes(element) {
+    return Array.from(element.attributes).filter((attr) => attr.name.startsWith("aria-")).map((attr) => attr.name);
+  }
+};
+var ariaValidator = new AriaValidator();
+var FocusValidator = class {
+  constructor() {
+    this.focusHistory = [];
+    this.isActive = false;
+    this.handleFocusIn = (event) => {
+      const target = event.target;
+      if (target && target !== document.body) {
+        this.focusHistory.push(target);
+        if (this.focusHistory.length > 10) {
+          this.focusHistory.shift();
+        }
+        this.validateFocusVisible(target);
+      }
+    };
+    this.handleFocusOut = (_event) => {
+    };
+  }
+  /**
+   * Start monitoring focus changes
+   */
+  start() {
+    if (!isDevelopment() || this.isActive) {
+      return;
+    }
+    document.addEventListener("focusin", this.handleFocusIn);
+    document.addEventListener("focusout", this.handleFocusOut);
+    this.isActive = true;
+  }
+  /**
+   * Stop monitoring focus changes
+   */
+  stop() {
+    if (!this.isActive) {
+      return;
+    }
+    document.removeEventListener("focusin", this.handleFocusIn);
+    document.removeEventListener("focusout", this.handleFocusOut);
+    this.isActive = false;
+    this.focusHistory = [];
+  }
+  /**
+   * Validate that focus is visible
+   */
+  validateFocusVisible(element) {
+    if (!isDevelopment()) {
+      return;
+    }
+    if (!(element instanceof HTMLElement)) {
+      return;
+    }
+    const computedStyle = window.getComputedStyle(element);
+    const outline = computedStyle.outline;
+    const outlineWidth = computedStyle.outlineWidth;
+    const hasFocusIndicator = outline !== "none" && outlineWidth !== "0px" && outlineWidth !== "0";
+    if (!hasFocusIndicator) {
+      const hasCustomFocus = element.hasAttribute("data-focus-visible-added") || element.matches(":focus-visible");
+      if (!hasCustomFocus) {
+        WarningSystem.warn(
+          createWarning({
+            code: WarningCodes.FOCUS_NOT_VISIBLE,
+            severity: "warn",
+            category: "focus-management",
+            message: "Focused element has no visible focus indicator",
+            element,
+            wcag: {
+              criterion: "2.4.7",
+              level: "AA",
+              url: WCAGUrls["2.4.7"]
+            },
+            fixes: [
+              {
+                description: "Add a visible outline or border on focus",
+                example: `.my-element:focus {
+  outline: 2px solid blue;
+  outline-offset: 2px;
+}`
+              },
+              {
+                description: "Use :focus-visible for keyboard-only focus indicators",
+                example: `.my-element:focus-visible {
+  outline: 2px solid blue;
+}`
+              },
+              {
+                description: "Use FocusVisible from @a13y/core",
+                example: `import { FocusVisible } from '@a13y/core/runtime/focus';
+FocusVisible.init();
+
+// Then in CSS:
+[data-focus-visible-added] {
+  outline: 2px solid blue;
+}`
+              }
+            ]
+          })
+        );
+      }
+    }
+  }
+  /**
+   * Validate focus trap
+   */
+  validateFocusTrap(container, expectedTrapped) {
+    if (!isDevelopment()) {
+      return;
+    }
+    const focusableElements = this.getFocusableElements(container);
+    if (focusableElements.length === 0) {
+      WarningSystem.warn(
+        createWarning({
+          code: WarningCodes.FOCUS_TRAP_BROKEN,
+          severity: "error",
+          category: "focus-management",
+          message: "Focus trap container has no focusable elements",
+          element: container,
+          wcag: {
+            criterion: "2.1.2",
+            level: "A",
+            url: WCAGUrls["2.1.2"]
+          },
+          fixes: [
+            {
+              description: "Add at least one focusable element inside the container",
+              example: `<div role="dialog">
+  <button>Close</button>
+</div>`
+            },
+            {
+              description: 'Make container focusable with tabindex="-1"',
+              example: `<div role="dialog" tabindex="-1">
+  Content
+</div>`
+            }
+          ]
+        })
+      );
+    }
+    if (expectedTrapped && focusableElements.length > 0) {
+      const lastElement = focusableElements[focusableElements.length - 1];
+      if (document.activeElement === lastElement) {
+        const hasTabHandler = container.getAttribute("data-focus-trap") === "true";
+        if (!hasTabHandler) {
+          WarningSystem.warn(
+            createWarning({
+              code: WarningCodes.FOCUS_TRAP_BROKEN,
+              severity: "warn",
+              category: "focus-management",
+              message: "Focus trap may not be working correctly",
+              element: container,
+              wcag: {
+                criterion: "2.1.2",
+                level: "A",
+                url: WCAGUrls["2.1.2"]
+              },
+              fixes: [
+                {
+                  description: "Use createFocusTrap from @a13y/core",
+                  example: `import { createFocusTrap } from '@a13y/core/runtime/focus';
+
+const trap = createFocusTrap(container);
+trap.activate();`
+                }
+              ]
+            })
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Validate focus order
+   */
+  validateFocusOrder(container) {
+    if (!isDevelopment()) {
+      return;
+    }
+    const focusableElements = this.getFocusableElements(container);
+    focusableElements.forEach((element) => {
+      const tabindex = element.getAttribute("tabindex");
+      if (tabindex && parseInt(tabindex, 10) > 0) {
+        WarningSystem.warn(
+          createWarning({
+            code: WarningCodes.FOCUS_ORDER_INVALID,
+            severity: "warn",
+            category: "focus-management",
+            message: `Positive tabindex (${tabindex}) creates confusing focus order`,
+            element,
+            wcag: {
+              criterion: "2.4.3",
+              level: "A",
+              url: WCAGUrls["2.4.3"]
+            },
+            fixes: [
+              {
+                description: "Remove positive tabindex and restructure DOM",
+                example: `<!-- Instead of using tabindex to change order -->
+<div tabindex="2">Second</div>
+<div tabindex="1">First</div>
+
+<!-- Restructure DOM to match desired order -->
+<div tabindex="0">First</div>
+<div tabindex="0">Second</div>`
+              }
+            ]
+          })
+        );
+      }
+    });
+  }
+  /**
+   * Track focus restoration after actions
+   */
+  expectFocusRestoration(expectedElement, action) {
+    if (!isDevelopment()) {
+      return;
+    }
+    setTimeout(() => {
+      if (document.activeElement !== expectedElement) {
+        WarningSystem.warn(
+          createWarning({
+            code: WarningCodes.FOCUS_NOT_RESTORED,
+            severity: "warn",
+            category: "focus-management",
+            message: `Focus was not restored after ${action}`,
+            element: expectedElement,
+            wcag: {
+              criterion: "2.4.3",
+              level: "A",
+              url: WCAGUrls["2.4.3"]
+            },
+            fixes: [
+              {
+                description: "Restore focus to the expected element",
+                example: `// Save focus before action
+const returnElement = document.activeElement;
+
+// Perform action
+performAction();
+
+// Restore focus
+returnElement?.focus();`
+              },
+              {
+                description: "Use FocusManager.saveFocus()",
+                example: `import { FocusManager } from '@a13y/core/runtime/focus';
+
+const restore = FocusManager.saveFocus();
+performAction();
+restore();`
+              }
+            ]
+          })
+        );
+      }
+    }, 100);
+  }
+  getFocusableElements(container) {
+    const selector = [
+      "a[href]",
+      "button:not([disabled])",
+      "input:not([disabled])",
+      "select:not([disabled])",
+      "textarea:not([disabled])",
+      '[tabindex]:not([tabindex="-1"])'
+    ].join(",");
+    return Array.from(container.querySelectorAll(selector));
+  }
+};
+var focusValidator = new FocusValidator();
+var KeyboardValidator = class {
+  /**
+   * Validate that interactive elements are keyboard accessible
+   */
+  validateInteractiveElement(element) {
+    if (!isDevelopment()) {
+      return;
+    }
+    const info = this.analyzeElement(element);
+    if (info.hasClickHandler && !info.isFocusable) {
+      WarningSystem.warn(
+        createWarning({
+          code: WarningCodes.NOT_KEYBOARD_ACCESSIBLE,
+          severity: "error",
+          category: "keyboard-navigation",
+          message: "Interactive element is not keyboard accessible",
+          element,
+          wcag: {
+            criterion: "2.1.1",
+            level: "A",
+            url: WCAGUrls["2.1.1"]
+          },
+          fixes: [
+            {
+              description: "Use a semantic button element",
+              example: `<button onClick={handleClick}>Click me</button>`
+            },
+            {
+              description: 'Add tabindex="0" and keyboard handlers',
+              example: `<div
+  tabindex="0"
+  onClick={handleClick}
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      handleClick();
+    }
+  }}
+>
+  Click me
+</div>`
+            }
+          ]
+        })
+      );
+    }
+    if (info.hasClickHandler && info.isFocusable && !info.hasKeyHandler) {
+      const isSemanticInteractive = element instanceof HTMLButtonElement || element instanceof HTMLAnchorElement && element.hasAttribute("href") || element instanceof HTMLInputElement;
+      if (!isSemanticInteractive) {
+        WarningSystem.warn(
+          createWarning({
+            code: WarningCodes.MISSING_KEYBOARD_HANDLER,
+            severity: "warn",
+            category: "keyboard-navigation",
+            message: "Element has click handler but no keyboard event handler",
+            element,
+            wcag: {
+              criterion: "2.1.1",
+              level: "A",
+              url: WCAGUrls["2.1.1"]
+            },
+            fixes: [
+              {
+                description: "Add onKeyDown handler for Enter and Space keys",
+                example: `element.addEventListener('keydown', (e) => {
+  if (e.key === 'Enter' || e.key === ' ') {
+    e.preventDefault();
+    // Trigger click or custom action
+  }
+});`
+              }
+            ]
+          })
+        );
+      }
+    }
+    this.checkForDivButton(element);
+  }
+  /**
+   * Validate that a container's children are reachable via keyboard
+   */
+  validateContainer(container) {
+    if (!isDevelopment()) {
+      return;
+    }
+    const interactiveElements = this.findInteractiveElements(container);
+    interactiveElements.forEach((info) => {
+      if (info.hasClickHandler && !info.isFocusable) {
+        this.validateInteractiveElement(info.element);
+      }
+    });
+  }
+  /**
+   * Validate roving tabindex implementation
+   */
+  validateRovingTabindex(container) {
+    if (!isDevelopment()) {
+      return;
+    }
+    const items = Array.from(container.children);
+    const tabindexValues = items.map(
+      (item) => item.hasAttribute("tabindex") ? parseInt(item.getAttribute("tabindex") || "0", 10) : null
+    );
+    const zeroCount = tabindexValues.filter((v) => v === 0).length;
+    const negativeOneCount = tabindexValues.filter((v) => v === -1).length;
+    if (zeroCount !== 1 || negativeOneCount !== items.length - 1) {
+      WarningSystem.warn(
+        createWarning({
+          code: WarningCodes.ROVING_TABINDEX_BROKEN,
+          severity: "warn",
+          category: "keyboard-navigation",
+          message: "Roving tabindex pattern is not correctly implemented",
+          element: container,
+          wcag: {
+            criterion: "2.1.1",
+            level: "A",
+            url: WCAGUrls["2.1.1"]
+          },
+          fixes: [
+            {
+              description: 'Set exactly one item to tabindex="0" and all others to tabindex="-1"',
+              example: `<!-- Correct roving tabindex -->
+<div role="toolbar">
+  <button tabindex="0">First (active)</button>
+  <button tabindex="-1">Second</button>
+  <button tabindex="-1">Third</button>
+</div>`
+            },
+            {
+              description: "Use RovingTabindexManager from @a13y/core",
+              example: `import { RovingTabindexManager } from '@a13y/core/runtime/keyboard';
+
+const manager = new RovingTabindexManager(toolbar, {
+  orientation: 'horizontal',
+});
+manager.init();`
+            }
+          ]
+        })
+      );
+    }
+  }
+  /**
+   * Check for escape key handler in dialogs/modals
+   */
+  validateEscapeHandler(container, shouldHaveEscape) {
+    if (!isDevelopment() || !shouldHaveEscape) {
+      return;
+    }
+    const hasEscapeAttr = container.hasAttribute("data-escape-closes");
+    if (!hasEscapeAttr) {
+      WarningSystem.warn(
+        createWarning({
+          code: WarningCodes.MISSING_ESC_HANDLER,
+          severity: "warn",
+          category: "keyboard-navigation",
+          message: "Dialog/Modal should close on Escape key",
+          element: container,
+          wcag: {
+            criterion: "2.1.2",
+            level: "A",
+            url: WCAGUrls["2.1.2"]
+          },
+          fixes: [
+            {
+              description: "Add Escape key handler",
+              example: `container.addEventListener('keydown', (e) => {
+  if (e.key === 'Escape') {
+    closeDialog();
+  }
+});`
+            },
+            {
+              description: "Use createFocusTrap with onEscape callback",
+              example: `import { createFocusTrap } from '@a13y/core/runtime/focus';
+
+const trap = createFocusTrap(dialog, {
+  onEscape: () => closeDialog(),
+});`
+            }
+          ]
+        })
+      );
+    }
+  }
+  /**
+   * Analyze an element for keyboard accessibility
+   */
+  analyzeElement(element) {
+    const hasClickHandler = element.hasAttribute("onclick") || element.hasAttribute("@click") || element.hasAttribute("v-on:click") || // Check for React synthetic events (harder to detect)
+    Object.keys(element).some((key) => key.startsWith("__react"));
+    const hasKeyHandler = element.hasAttribute("onkeydown") || element.hasAttribute("onkeyup") || element.hasAttribute("onkeypress") || element.hasAttribute("@keydown") || element.hasAttribute("v-on:keydown");
+    const isFocusable = this.isFocusable(element);
+    return {
+      element,
+      hasClickHandler,
+      hasKeyHandler,
+      isFocusable
+    };
+  }
+  /**
+   * Check if element is focusable
+   */
+  isFocusable(element) {
+    if (element instanceof HTMLButtonElement || element instanceof HTMLInputElement || element instanceof HTMLSelectElement || element instanceof HTMLTextAreaElement || element instanceof HTMLAnchorElement && element.hasAttribute("href")) {
+      return true;
+    }
+    const tabindex = element.getAttribute("tabindex");
+    if (tabindex !== null && parseInt(tabindex, 10) >= 0) {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Find all interactive elements in a container
+   */
+  findInteractiveElements(container) {
+    const elements = [];
+    const clickableSelector = "[onclick], [data-clickable]";
+    const clickables = container.querySelectorAll(clickableSelector);
+    clickables.forEach((element) => {
+      elements.push(this.analyzeElement(element));
+    });
+    return elements;
+  }
+  /**
+   * Check for div/span styled as button (antipattern)
+   */
+  checkForDivButton(element) {
+    const tagName = element.tagName.toLowerCase();
+    if (tagName === "div" || tagName === "span") {
+      const role = element.getAttribute("role");
+      const hasClickHandler = element.hasAttribute("onclick") || Object.keys(element).some((key) => key.startsWith("__react"));
+      if ((role === "button" || hasClickHandler) && !this.isFocusable(element)) {
+        WarningSystem.warn(
+          createWarning({
+            code: WarningCodes.DIV_BUTTON,
+            severity: "warn",
+            category: "semantic-html",
+            message: `<${tagName}> used as button - use <button> instead`,
+            element,
+            fixes: [
+              {
+                description: "Use a semantic <button> element",
+                example: `<!-- Instead of -->
+<div role="button" onClick={handleClick}>Click me</div>
+
+<!-- Use -->
+<button onClick={handleClick}>Click me</button>`
+              },
+              {
+                description: "If you must use a div, add tabindex and keyboard handlers",
+                example: `<div
+  role="button"
+  tabindex="0"
+  onClick={handleClick}
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      handleClick();
+    }
+  }}
+>
+  Click me
+</div>`
+              }
+            ]
+          })
+        );
+      }
+    }
+  }
+};
+var keyboardValidator = new KeyboardValidator();
+
+export { AriaValidator, FocusValidator, KeyboardValidator, WCAGUrls, WarningCodes, WarningSystem, ariaValidator, assertFocusVisible, assertHasAccessibleName, assertKeyboardAccessible, assertValidAriaAttributes, assertValidTabindex, createWarning, focusValidator, invariant, keyboardValidator };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map