props

Библиотека Aria-query в JavaScript предоставляет удобные структуры для работы с ARIA-атрибутами, ролями и их связями. Основная цель модуля props — хранение и валидация свойств, которые могут быть применены к элементам с определённой ролью, обеспечивая корректность с точки зрения доступности (accessibility).

Структура props

props представляет собой объект, где ключи — это имена ARIA-атрибутов, а значения — их метаданные и правила использования. Каждое свойство содержит следующую информацию:

  • type — тип значения: string, boolean, integer, token, idref и т. д.
  • values — допустимые значения (для token и перечисляемых типов).
  • required — булев флаг, указывающий, обязательно ли свойство для определённых ролей.
  • defaultValue — значение по умолчанию, если оно не указано в элементе.
  • allowUndefined — возможность отсутствия атрибута на элементе.

Пример структуры свойства:

{
  "aria-hidden": {
    type: "boolean",
    required: false,
    defaultValue: false
  },
  "aria-label": {
    type: "string",
    required: false
  },
  "aria-orientation": {
    type: "token",
    values: ["horizontal", "vertical"],
    required: false
  }
}

В этом примере aria-hidden имеет тип boolean с дефолтным значением false, aria-label ожидает строку, а aria-orientation принимает только horizontal или vertical.

Получение пропсов

Библиотека предоставляет методы для получения пропсов по конкретной роли. Основной метод — getProps(roleName). Он возвращает объект с допустимыми свойствами для указанной роли:

import { roles, props } from "aria-query";

const buttonProps = props.get("button");
console.log(buttonProps);

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

Валидация значений

Каждый пропс содержит информацию о типе и возможных значениях. Для проверки корректности значения используется метод валидации. Пример проверки aria-orientation:

const orientationProp = props.get("aria-orientation");

function validateOrientation(value) {
  if (!orientationProp.values.includes(value)) {
    throw new Error(`Недопустимое значение ${value} для aria-orientation`);
  }
  return true;
}

validateOrientation("horizontal"); // корректно
validateOrientation("diagonal");   // выбросит ошибку

Такой подход позволяет избежать некорректного использования ARIA-атрибутов, что критично для поддержания доступности веб-приложений.

Связь пропсов с ролями

Каждый пропс может быть общим или специфичным для роли. Общие пропсы применяются ко всем элементам (aria-hidden, aria-label), а специфичные ограничены набором ролей (aria-checked для checkbox, switch и т. д.).

Для получения ролей, поддерживающих конкретный пропс:

const rolesSupportingChecked = props.getRoles("aria-checked");
console.log(rolesSupportingChecked); // ["checkbox", "menuitemcheckbox", "switch"]

Это важно при динамическом рендеринге элементов, чтобы не допустить применение неподдерживаемого атрибута.

Дефолтные значения и опциональные пропсы

Пропсы могут иметь значение по умолчанию и быть необязательными. При генерации HTML это позволяет:

  • Автоматически добавлять дефолтные атрибуты.
  • Исключать необязательные пропсы, если их значение совпадает с дефолтным.
  • Обеспечивать единообразие и минимизацию разметки.

Пример автоматического применения дефолта:

const buttonProps = props.get("button");

const appliedProps = Object.keys(buttonProps).reduce((acc, key) => {
  const propMeta = buttonProps[key];
  if (propMeta.defaultValue !== undefined) {
    acc[key] = propMeta.defaultValue;
  }
  return acc;
}, {});

console.log(appliedProps); // { "aria-hidden": false }

Типизация и токены

Aria-query строго разделяет типы пропсов:

  • boolean — true/false
  • string — любая строка
  • integer — целое число
  • idref / idrefs — идентификаторы других элементов
  • token / token list — фиксированный набор строковых значений
  • tristate — true | false | mixed

Использование токенов гарантирует, что элемент не получит некорректное значение, например, нельзя установить aria-orientation="diagonal".

Работа с наследуемыми пропсами

Некоторые ARIA-пропсы могут наследоваться от родителя (aria-owns, aria-labelledby). Aria-query предоставляет возможность:

  • Проверять корректность ссылок на другие элементы.
  • Генерировать список ID для токенов idref и idrefs.
  • Встраивать проверку на циклические ссылки.
const labelIds = ["label1", "label2"];
const propMeta = props.get("aria-labelledby");

if (propMeta.type === "idrefs" && Array.isArray(labelIds)) {
  // корректно
}

Интеграция с линтерами и React

В экосистеме React и других UI-библиотек props Aria-query часто используется для:

  • Автоматической типизации пропсов компонентов.
  • Создания хуков для валидации ARIA-атрибутов.
  • Генерации подсказок IDE по допустимым значениям.

Пример валидации в React-компоненте:

import { props } from "aria-query";

function Button({ "aria-hidden": hidden, ...rest }) {
  const ariaHiddenProp = props.get("aria-hidden");
  if (typeof hidden !== ariaHiddenProp.type) {
    throw new Error(`aria-hidden должен быть boolean`);
  }
  return <button aria-hidden={hidden} {...rest} />;
}

Заключение по props

Структура props в Aria-query обеспечивает строгий контроль ARIA-атрибутов, их типов, значений и роли применения. Она позволяет создавать доступные интерфейсы, предотвращает ошибки в разметке и интегрируется с инструментами проверки кода и фреймворками UI, делая работу с ARIA стандартизированной и безопасной.

Оглавление