Структура библиотека и основные экспорты

Библиотека Aria-query предназначена для работы с семантическими и ARIA-атрибутами в контексте веб-разработки. Она позволяет получать детальную информацию о ролях, состояниях и свойствах элементов интерфейса, что особенно важно при создании доступных приложений. Основная архитектура библиотеки строится вокруг трех ключевых сущностей: roles, properties и elementRoles.

Модуль roles

Массив или объект roles содержит описание всех ARIA-ролей, определенных стандартом WAI-ARIA. Каждая роль включает:

  • name — уникальное имя роли (например, button, checkbox).
  • abstract — булево значение, указывающее, является ли роль абстрактной (то есть не применяемой напрямую к DOM-элементу).
  • requiredContextRole — массив ролей, в контексте которых роль может использоваться.
  • requiredOwnedElements — список ролей, которые обязательно должны быть дочерними для данной роли.
  • props — объект свойств, определяющий допустимые ARIA-атрибуты для роли, их типы и значения.

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

import { roles } from 'aria-query';

const buttonRole = roles.get('button');
console.log(buttonRole.props['aria-pressed']); // выводит информацию о свойстве aria-pressed

Ключевой момент: roles — это Map, что обеспечивает быстрый доступ к любой роли по её имени.

Модуль elementRoles

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

Структура объекта:

  • ключ — название HTML-элемента (div, button, ul и др.).
  • значение — Set ролей, допустимых для данного элемента.

Пример:

import { elementRoles } from 'aria-query';

const buttonElements = elementRoles.get('button');
console.log(buttonElements.has('button')); // true
console.log(buttonElements.has('menu')); // false

Важно: библиотека учитывает ARIA в контексте HTML5, что делает проверки валидными для современных веб-приложений.

Модуль properties

properties содержит описание всех ARIA-свойств и состояний (aria- атрибутов). Для каждого свойства указано:

  • name — имя свойства (aria-hidden, aria-checked и др.).
  • type — тип значения (boolean, tristate, string, idref, token и т.д.).
  • values — допустимые значения (для свойств с фиксированным набором).

Пример:

import { properties } from 'aria-query';

const hiddenProp = properties.get('aria-hidden');
console.log(hiddenProp.type); // 'boolean'

Особенности: все свойства представлены через Map, что упрощает проверку типов и валидность значений при динамическом присвоении атрибутов.

Основные экспортируемые функции

Aria-query предоставляет набор утилит для работы с ролями и свойствами:

  • roles.get(roleName) — получение объекта роли по имени.
  • elementRoles.get(elementName) — получение набора ролей для HTML-элемента.
  • properties.get(propertyName) — получение информации о конкретном ARIA-свойстве.
  • roles.keys(), properties.keys(), elementRoles.keys() — перечисление всех доступных ключей.

Дополнительно возможна фильтрация:

// Получение всех интерактивных ролей
const interactiveRoles = Array.from(roles.values()).filter(role => role.props['aria-disabled']);

Организация кода внутри библиотеки

  1. Map-структуры — основа хранения ролей, свойств и соответствий элементов.
  2. Типизация и метаданные — каждая сущность содержит информацию о типе, требуемых контекстах и допустимых значениях.
  3. Иммутабельность — данные не изменяются напрямую, что исключает ошибки при глобальном использовании.
  4. Интеграция с валидаторами — библиотека используется как источник истины для линтеров и тестов на доступность.

Практическая ценность

Использование Aria-query позволяет:

  • Автоматически проверять совместимость HTML-элементов и ARIA-ролей.
  • Получать строгую типизацию ARIA-свойств.
  • Реализовывать динамические интерфейсы с корректной семантикой.
  • Минимизировать ошибки доступности, которые сложно выявить визуально.

Библиотека действует как единственный источник правды по ARIA, облегчая построение доступных веб-компонентов и интеграцию с тестовыми фреймворками.

Оглавление