or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

aria-properties.mddom-elements.mdelement-role-mappings.mdindex.mdrole-definitions.mdrole-element-mappings.md
tile.json

tessl/npm-aria-query

Programmatic access to the WAI-ARIA 1.2 Roles Model specification with comprehensive role definitions, HTML element mappings, and ARIA property data.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/aria-query@5.3.x

To install, run

npx @tessl/cli install tessl/npm-aria-query@5.3.0

index.mddocs/

ARIA Query

ARIA Query provides comprehensive programmatic access to the WAI-ARIA 1.2 Roles Model specification. It offers a complete toolkit for developers building accessible web applications, linting tools, and assistive technology integrations that require standardized access to ARIA specification data.

Package Information

  • Package Name: aria-query
  • Package Type: npm
  • Language: JavaScript (with Flow types)
  • Installation: npm install aria-query

Core Imports

import { roles, elementRoles, roleElements, aria, dom } from "aria-query";

For CommonJS:

const { roles, elementRoles, roleElements, aria, dom } = require("aria-query");

Basic Usage

import { roles, elementRoles, roleElements } from "aria-query";

// Get ARIA role definition
const alertRole = roles.get('alert');
console.log(alertRole.props['aria-live']); // "assertive"

// Find roles for HTML elements
const buttonElement = { name: "button" };
const buttonRoles = elementRoles.get(buttonElement);
console.log(buttonRoles); // ['button']

// Find HTML elements for a role
const linkElements = roleElements.get('link');
console.log(linkElements); // [{ name: "a" }, { name: "link" }]

// Iterate over all roles using for...of
for (const [roleName, roleDefinition] of roles) {
  if (roleDefinition.abstract) {
    console.log(`${roleName} is abstract`);
  }
}

// Use forEach for iteration
roles.forEach((definition, name) => {
  if (definition.accessibleNameRequired) {
    console.log(`${name} requires accessible name`);
  }
});

Architecture

ARIA Query is built around five core Map-like collections that provide comprehensive access to ARIA specification data:

  • Role Definitions: Complete ARIA role specifications with properties, inheritance, and relationships
  • Element-to-Role Mappings: HTML elements mapped to their implicit ARIA roles
  • Role-to-Element Mappings: ARIA roles mapped to corresponding HTML elements
  • Property Definitions: ARIA properties and states with type and value specifications
  • DOM Element Registry: HTML element definitions with reserved status indicators

Each collection implements a consistent Map-like interface with iteration support, providing get(), has(), keys(), values(), entries(), and forEach() methods. All collections are also iterable using for...of loops and support the JavaScript iterator protocol via Symbol.iterator.

Capabilities

ARIA Role Definitions

Complete ARIA role specifications including properties, inheritance chains, and concept mappings. Essential for understanding role semantics and building accessibility tools.

const roles: TAriaQueryMap<Array<[string, ARIARoleDefinition]>, string, ARIARoleDefinition>;

interface ARIARoleDefinition {
  abstract: boolean;
  accessibleNameRequired: boolean;
  baseConcepts: Array<ARIARoleRelation>;
  childrenPresentational: boolean;
  nameFrom?: Array<ARIANameFromSources>;
  prohibitedProps: Array<string>;
  props: ARIAPropertyMap;
  relatedConcepts: Array<ARIARoleRelation>;
  requireContextRole?: Array<string>;
  requiredContextRole?: Array<string>;
  requiredOwnedElements?: Array<Array<string>>;
  requiredProps: ARIAPropertyMap;
  superClass: Array<Array<string>>;
}

Role Definitions

Element-to-Role Mappings

Maps HTML elements (with optional attributes) to their implicit ARIA roles. Critical for determining semantic meaning of HTML markup.

const elementRoles: TAriaQueryMap<Array<[ARIARoleRelationConcept, Array<string>]>, ARIARoleRelationConcept, Array<string>>;

interface ARIARoleRelationConcept {
  name: string;
  attributes?: Array<ARIARoleRelationConceptAttribute>;
  constraints?: Array<string>;
}

Element Role Mappings

Role-to-Element Mappings

Maps ARIA roles to the HTML elements that have those implicit roles. Useful for understanding which HTML elements provide specific ARIA semantics.

const roleElements: TAriaQueryMap<Array<[string, Array<ARIARoleRelationConcept>]>, string, Array<ARIARoleRelationConcept>>;

Role Element Mappings

ARIA Properties and States

Comprehensive definitions of all ARIA properties and states with type information and allowed values. Essential for validation and tooling.

const aria: TAriaQueryMap<Array<[string, ARIAPropertyDefinition]>, string, ARIAPropertyDefinition>;

interface ARIAPropertyDefinition {
  type: 'string' | 'id' | 'idlist' | 'integer' | 'number' | 'boolean' | 'token' | 'tokenlist' | 'tristate';
  values?: Array<string | boolean>;
  allowundefined?: boolean;
}

ARIA Properties

DOM Element Registry

Registry of HTML elements with their reserved status for ARIA role assignment. Helps determine which elements can accept role attributes.

const dom: TAriaQueryMap<Array<[string, DOMDefinition]>, string, DOMDefinition>;

interface DOMDefinition {
  reserved: boolean;
}

DOM Elements

Types

// Core Map interface implemented by all collections
interface TAriaQueryMap<E, K, V> {
  entries(): E;
  forEach(fn: (V, K, E) => void, thisArg?: any): void;
  get(key: K): V | null | undefined;
  has(key: K): boolean;
  keys(): Array<K>;
  values(): Array<V>;
  [Symbol.iterator](): Iterator<[K, V]>;
}

// ARIA role relation structure
interface ARIARoleRelation {
  module?: string;
  concept?: ARIARoleRelationConcept;
}

// HTML element concept with optional attributes
interface ARIARoleRelationConceptAttribute {
  name: string;
  value?: string | number;
  constraints?: Array<'undefined' | 'set' | '>1'>;
}

// ARIA property map for role definitions
type ARIAPropertyMap = {
  [Property in ARIAProperty]?: any;
};

// Name sources for accessible names
type ARIANameFromSources = 'author' | 'contents' | 'prohibited';