{"_id":"@a11y-tools/aria-roles","name":"@a11y-tools/aria-roles","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@a11y-tools/aria-roles","version":"1.0.0","description":"A utility for fetching valid ARIA roles dynamically, validating roles, and providing type-safe access to ARIA role names.","type":"module","main":"dist/index.js","module":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"directories":{"test":"test"},"scripts":{"build":"tsc","test":"vitest","prepublishOnly":"npm run build","lint":"tsc --noEmit"},"repository":{"type":"git","url":"git+https://github.com/a11ytools/aria-roles.git"},"keywords":["aria","aria roles","aria utilities","accessibility","a11y","web accessibility","aria attributes","assistive technology","typescript","type-safe"],"author":{"name":"Venkata Phanindra Kumar Janapareddy","url":"https://github.com/venkatajanapareddy"},"license":"MIT","bugs":{"url":"https://github.com/a11ytools/aria-roles/issues"},"homepage":"https://github.com/a11ytools/aria-roles#readme","devDependencies":{"@types/node":"^22.13.9","typescript":"^5.8.2","vitest":"^3.0.8"},"publishConfig":{"access":"public"},"_id":"@a11y-tools/aria-roles@1.0.0","gitHead":"3c5abab209b4c095fd733a9c350855dcf787d04f","_nodeVersion":"20.19.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-9rLDOQxgwJ6l9zhikwPx1L3fmsCO1aR19C0mBY5Zfdge9HmpbRNksynEjckqY8uSL/58mRTfSfZ3/uLWGUCwoA==","shasum":"cdf079ebfda46b596e2906e7b61f7f83c72fb98f","tarball":"https://registry.npmjs.org/@a11y-tools/aria-roles/-/aria-roles-1.0.0.tgz","fileCount":7,"unpackedSize":12437,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDcLN0ovxcrThivsLaktdO5hFee8Y3bsSUOB8I4V11W0AiBIyMT9Jw6z9gUwp4XW20xAsS1kH7byBMi57e5GMrIbZA=="}]},"_npmUser":{"name":"zenluv","email":"venkatajanapareddy9@gmail.com"},"maintainers":[{"name":"zenluv","email":"venkatajanapareddy9@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/aria-roles_1.0.0_1747004427803_0.6032327231448087"},"_hasShrinkwrap":false}},"time":{"created":"2025-05-11T23:00:27.742Z","1.0.0":"2025-05-11T23:00:27.980Z","modified":"2025-05-11T23:00:28.244Z"},"maintainers":[{"name":"zenluv","email":"venkatajanapareddy9@gmail.com"}],"description":"A utility for fetching valid ARIA roles dynamically, validating roles, and providing type-safe access to ARIA role names.","homepage":"https://github.com/a11ytools/aria-roles#readme","keywords":["aria","aria roles","aria utilities","accessibility","a11y","web accessibility","aria attributes","assistive technology","typescript","type-safe"],"repository":{"type":"git","url":"git+https://github.com/a11ytools/aria-roles.git"},"author":{"name":"Venkata Phanindra Kumar Janapareddy","url":"https://github.com/venkatajanapareddy"},"bugs":{"url":"https://github.com/a11ytools/aria-roles/issues"},"license":"MIT","readme":"# aria-roles\n\n**aria-roles** is a lightweight utility library that provides a reliable way to fetch valid ARIA roles dynamically. It simplifies accessibility development by preventing hardcoded role values and enabling validation for better UI accessibility compliance.\n\n## 🚀 Features\n- 📜 Retrieve a complete, up-to-date list of all valid ARIA roles\n- ✅ Validate whether a given role is a recognized ARIA role\n- 🔒 Type-safe access to ARIA role names\n- ⚡ Lightweight, fast, and dependency-free\n- 🔍 Designed for use in accessibility tooling, testing, and frontend frameworks\n\n## 📦 Installation\n```sh\nnpm install @a11y-tools/aria-roles\n```\n\n## 🔧 Usage\n\n### Basic Usage\n```js\nimport { getAllAriaRoles, isValidAriaRole, ariaRoles } from \"@a11y-tools/aria-roles\";\n\n// Get all valid ARIA roles\nconsole.log(getAllAriaRoles()); // Returns an array of valid ARIA roles\n\n// Validate a role\nconsole.log(isValidAriaRole(\"button\")); // true\nconsole.log(isValidAriaRole(\"fake-role\")); // false\n\n// Type-safe access to role names\nelement.setAttribute('role', ariaRoles.button);\nelement.setAttribute('role', ariaRoles.tabpanel);\n```\n\n### TypeScript Usage\n```ts\nimport { AriaRole, ariaRoles, isValidAriaRole } from \"@a11y-tools/aria-roles\";\n\n// Type-safe role definition\nconst myRole: AriaRole = ariaRoles.button;\n\n// Type narrowing with isValidAriaRole\nfunction setRole(element: HTMLElement, role: string) {\n  if (isValidAriaRole(role)) {\n    // TypeScript knows 'role' is of type AriaRole here\n    element.setAttribute('role', role);\n  } else {\n    console.warn(`Invalid ARIA role: ${role}`);\n  }\n}\n```\n\n### React Example\n```tsx\nimport React from 'react';\nimport { ariaRoles } from '@a11y-tools/aria-roles';\n\nfunction AccessibleButton({ children, onClick }) {\n  return (\n    <div \n      role={ariaRoles.button} \n      onClick={onClick}\n      tabIndex={0}\n      onKeyDown={(e) => {\n        if (e.key === 'Enter' || e.key === ' ') {\n          onClick();\n        }\n      }}\n    >\n      {children}\n    </div>\n  );\n}\n```\n\n### Vue Example\n```vue\n<template>\n  <div \n    :role=\"ariaRoles.button\"\n    @click=\"onClick\"\n    tabindex=\"0\"\n    @keydown=\"handleKeyDown\"\n  >\n    <slot></slot>\n  </div>\n</template>\n\n<script>\nimport { ariaRoles } from '@a11y-tools/aria-roles';\n\nexport default {\n  setup() {\n    const handleKeyDown = (e) => {\n      if (e.key === 'Enter' || e.key === ' ') {\n        onClick();\n      }\n    };\n    \n    return {\n      ariaRoles,\n      handleKeyDown\n    };\n  },\n  methods: {\n    onClick() {\n      // Handle click\n    }\n  }\n}\n</script>\n```\n\n### 🧪 Testing Example\n\n```tsx\nimport { render, screen } from '@testing-library/react';\nimport { ariaRoles, isValidAriaRole } from '@a11y-tools/aria-roles';\n\n// React Testing Library - use ariaRoles for type-safe queries\ntest('Component uses correct ARIA roles', () => {\n  render(<MyComponent />);\n  \n  // Query elements by their roles using ariaRoles\n  const button = screen.getByRole(ariaRoles.button);\n  const navigation = screen.getByRole(ariaRoles.navigation);\n  \n  // Verify elements have proper attributes\n  expect(button).toHaveAttribute('aria-pressed', 'false');\n  expect(navigation).toBeInTheDocument();\n});\n\n// Validate all roles in a component\ntest('All roles are valid', () => {\n  const { container } = render(<MyComponent />);\n  \n  // Check that all role attributes are valid\n  container.querySelectorAll('[role]').forEach(element => {\n    const role = element.getAttribute('role');\n    expect(isValidAriaRole(role)).toBe(true);\n  });\n});\n```\n\n## 🔄 API Reference\n\n### `getAllAriaRoles()`\nReturns an array of all valid ARIA roles as strings.\n\n```ts\nfunction getAllAriaRoles(): AriaRole[]\n```\n\n### `isValidAriaRole(role)`\nValidates if a string is a valid ARIA role. In TypeScript, this function acts as a type guard.\n\n```ts\nfunction isValidAriaRole(role: string): role is AriaRole\n```\n\n### `ariaRoles`\nAn object that provides type-safe access to all ARIA role names. Each property is named after an ARIA role and returns the role name as a string.\n\n```ts\nconst ariaRoles: Record<AriaRole, AriaRole>\n```\n\n### `AriaRole` (TypeScript only)\nA TypeScript type that represents all valid ARIA roles.\n\n```ts\ntype AriaRole = 'alert' | 'alertdialog' | 'application' | /* ... */;\n```\n\n## 🤝 Contributing\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## 📜 License\nThis project is licensed under the MIT License.\n","readmeFilename":"README.md","_rev":"1-6b1de497b334fa441c0550edef335f90"}