nameFrom

aria-query — это библиотека для работы с ARIA-атрибутами и ролями в JavaScript. Она предоставляет возможность валидировать, искать и сопоставлять роли, состояния и свойства ARIA, что особенно важно при разработке доступных веб-приложений. В основе работы лежит коллекция спецификаций ARIA из официального стандарта WAI-ARIA.

Ключевые понятия:

  • Roles (роли): описывают назначение элемента интерфейса, например button, checkbox, dialog.
  • States and Properties (состояния и свойства): описывают текущее состояние элемента или его характеристики, например aria-checked, aria-disabled.
  • Elements (элементы): HTML-теги, которые могут использовать ARIA-атрибуты.

aria-query позволяет работать с этими сущностями через JavaScript-объекты и коллекции, что упрощает проверку совместимости ролей и атрибутов.

Коллекции ролей и атрибутов

Библиотека предоставляет несколько основных коллекций:

  1. roles Объект roles содержит все роли ARIA с их определениями. Каждая роль описана следующими свойствами:

    • name: стандартное имя роли.
    • abstract: булево значение, указывающее, что роль абстрактная и не применяется напрямую к элементу.
    • requiredProps: список ARIA-свойств, обязательных для роли.
    • superClass: массив родительских ролей, обеспечивающих наследование поведения.
    • props: все свойства, доступные для данной роли.

Пример использования:

const { roles } = require('aria-query');

const buttonRole = roles.get('button');
console.log(buttonRole.requiredProps); // []
console.log(buttonRole.superClass); // [['command', 'widget']]
  1. elementRoles Сопоставляет HTML-элементы с ролями ARIA. Полезно для автоматической проверки, какие роли допустимы для конкретного тега.
const { elementRoles } = require('aria-query');

const rolesForDiv = elementRoles.get('div'); 
console.log([...rolesForDiv]); // Set { 'generic', 'region', 'main', ... }
  1. ariaAttributes Коллекция всех ARIA-атрибутов с указанием их типов (boolean, tristate, string, idref и др.) и поддерживаемых значений.
const { aria } = require('aria-query');

console.log(aria.get('aria-disabled'));
// { type: 'boolean', values: [true, false] }

Работа с ролями

aria-query позволяет динамически проверять совместимость элементов и ролей, а также наследование атрибутов:

  • Проверка, является ли роль валидной:
const { roles } = require('aria-query');

console.log(roles.has('checkbox')); // true
console.log(roles.has('nonexistent')); // false
  • Получение обязательных и допустимых свойств роли:
const checkboxRole = roles.get('checkbox');
console.log(checkboxRole.requiredProps); // ['aria-checked']
console.log(checkboxRole.props); 
// Map { 'aria-checked' => { type: 'tristate', values: [true, false, 'mixed'] }, ... }
  • Проверка наследования:
console.log(checkboxRole.superClass); // [['input', 'widget']]

Это позволяет строить сложные правила валидации и автогенерации доступных интерфейсов.

Совместимость элементов и ролей

С помощью elementRoles можно определить, какие роли поддерживаются конкретным HTML-элементом. Это важно для обеспечения семантики и доступности.

const { elementRoles, roles } = require('aria-query');

for (const role of elementRoles.get('a')) {
  const roleDef = roles.get(role);
  console.log(role, roleDef.abstract); 
}

Также можно фильтровать только конкретные совместимые роли, исключая абстрактные:

const compatibleRoles = [...elementRoles.get('div')].filter(
  roleName => !roles.get(roleName).abstract
);
console.log(compatibleRoles); // ['button', 'region', 'main', ...]

Работа с ARIA-атрибутами

aria-query предоставляет детальную информацию о свойствах и состояниях, включая их типы и допустимые значения.

const { aria } = require('aria-query');

const attr = aria.get('aria-expanded');
console.log(attr.type); // 'boolean'
console.log(attr.values); // [true, false]

Можно также проверить, какие роли требуют конкретный ARIA-атрибут:

const { roles } = require('aria-query');

const rolesRequiringExpanded = [...roles].filter(([name, def]) =>
  def.requiredProps.includes('aria-expanded')
);
console.log(rolesRequiringExpanded.map(([name]) => name)); // ['button', 'menuitem', ...]

Использование в проверках доступности

aria-query чаще всего используется для:

  • Linting и статического анализа: проверка, что роли и атрибуты применены корректно.
  • Генерации семантических компонентов: автоматическое присвоение ARIA-атрибутов на основе роли.
  • Валидации состояния: проверка обязательных атрибутов и допустимых значений.

Пример функции проверки:

function validateRole(elementTag, roleName, attributes) {
  const { roles, elementRoles, aria } = require('aria-query');

  if (!roles.has(roleName)) return false;
  const role = roles.get(roleName);

  if (!elementRoles.get(elementTag).has(roleName)) return false;

  for (const reqProp of role.requiredProps) {
    if (!(reqProp in attributes)) return false;
    const attrType = aria.get(reqProp).type;
    if (attrType === 'boolean' && typeof attributes[reqProp] !== 'boolean') return false;
  }

  return true;
}

console.log(validateRole('button', 'button', { 'aria-disabled': true })); // true

Эта функция демонстрирует практическое применение коллекций roles, elementRoles и aria для построения правил проверки доступности.

Взаимодействие с кастомными компонентами

Для React, Vue или других фреймворков можно использовать aria-query для генерации правильной роли и атрибутов на кастомных элементах:

function createAccessibleButton(props) {
  const { roles, aria } = require('aria-query');
  const role = 'button';
  const attributes = { 'aria-disabled': !!props.disabled };

  // Валидация
  const roleDef = roles.get(role);
  roleDef.requiredProps.forEach(req => {
    if (!(req in attributes)) attributes[req] = null;
  });

  return { role, ...attributes };
}

Это позволяет поддерживать корректную ARIA-семантику вне зависимости от того, что рендерится: стандартный <button> или кастомный <div> с функционалом кнопки.

Итоговые особенности библиотеки

  • Все коллекции основаны на официальной спецификации WAI-ARIA.
  • Предоставляет удобные объекты Map и Set для быстрого поиска и фильтрации.
  • Поддерживает проверку ролей, атрибутов и их совместимости с HTML-элементами.
  • Отлично интегрируется с инструментами статического анализа и генерации интерфейсов.
  • Позволяет создавать надежные и доступные пользовательские компоненты.
Оглавление