Breaking changes

Библиотека ally.js является мощным инструментом для управления доступностью веб-приложений, обеспечивая контроль над фокусом, навигацией и проверкой доступности элементов. Однако при обновлении версии могут возникать breaking changes — изменения, которые нарушают совместимость с предыдущими версиями. Понимание таких изменений критично для корректного обновления проектов и предотвращения ошибок в работе интерфейса.

Изменения API функций

В новых версиях ally.js некоторые методы подверглись модификации сигнатур:

  • tabbable() Ранее метод возвращал массив всех tabbable-элементов на странице, теперь он возвращает объект с дополнительной информацией о состоянии каждого элемента. Это означает, что прямой перебор массива через forEach или map необходимо заменять на обработку объекта с ключами elements и meta.

  • focusable() В предыдущих версиях метод возвращал булевое значение для каждого элемента, теперь он возвращает детализированный объект { element: HTMLElement, isFocusable: boolean }, что требует изменения логики проверок.

  • isFocusable() Сигнатура функции изменилась: параметр includeProgrammatic больше не поддерживается, вместо него используется опция в объекте конфигурации { includeProgrammatic: true/false }.

Эти изменения напрямую влияют на код, который использует функции для проверки доступности элементов или фильтрации фокусируемых объектов.

Модификация обработчиков событий

В старых версиях ally.js можно было подписываться на глобальные события через:

ally.when.key('tab', callback);

В новых версиях:

  • Поддержка ally.when.key была ограничена, рекомендуется использовать ally.when.focus с указанием конкретного селектора.
  • Обработчики теперь принимают объект события { type, target, previous } вместо простого DOM-события, что требует изменения существующей логики.

Изменения конфигурации и опций

Ранее глобальные настройки библиотеки устанавливались через:

ally.config({
  ignoreSelectors: ['.ignore'],
  tabOrder: 'document'
});

В новых версиях:

  • ignoreSelectors заменён на excludeSelectors с идентичной функциональностью, но новым именем.
  • tabOrder больше не поддерживает значение 'document'; вместо этого используется 'natural' или 'custom'.
  • Добавлены новые опции для управления фокусом внутри модальных окон и всплывающих элементов: { trapFocus: true, focusRoot: HTMLElement }.

Удаление устаревших методов

Некоторые методы полностью удалены:

  • ally.query.focusable() — заменён на ally.query.focusableElements().
  • ally.is.tabOrder() — больше не поддерживается, проверку порядка табуляции необходимо реализовывать вручную или через ally.query.tabSequence().
  • ally.when.key для глобального прослушивания клавиш — теперь работает только с фокусируемыми элементами, глобальная подписка невозможна.

Удаление методов может привести к критическим ошибкам при обновлении без адаптации к новой версии.

Изменения в структуре возвращаемых данных

Многие методы теперь возвращают объекты с дополнительными полями вместо простых массивов или булевых значений:

  • tabbable() → { elements: HTMLElement[], meta: { count: number } }
  • focusable() → { element: HTMLElement, isFocusable: boolean, reason?: string }[]
  • visible() → { element: HTMLElement, isVisible: boolean, hiddenBy?: HTMLElement[] }

Это позволяет более точно анализировать доступность, но требует пересмотра логики обхода элементов и фильтрации.

Влияние на обработку модальных окон и диалогов

Новая версия вводит строгие правила для работы с модальными диалогами:

  • Фокус теперь автоматически ограничен рамками модального окна при использовании опции trapFocus.
  • В старых версиях разработчик вручную управлял фокусом с помощью ally.query.focusable(). При обновлении необходимо заменить все вызовы ручного контроля на новые API с учетом focusRoot.

Совместимость с другими библиотеками

Изменения в сигнатурах функций и возвращаемых объектах могут вызвать конфликты с библиотеками, которые используют старый API ally.js для:

  • React- и Vue-компонентов, где фокус управляется через refs или directives.
  • UI-фреймворков, которые используют tabbable() и focusable() для кастомной навигации.

В таких случаях требуется адаптация к новым методам с учетом структуры возвращаемых данных.

Рекомендации при обновлении

  1. Перепроверить все вызовы методов tabbable(), focusable(), isFocusable() и заменить обработку массивов на обработку новых объектов.
  2. Заменить устаревшие методы на новые аналоги (query.focusableElements, query.tabSequence).
  3. Проверить обработку событий фокуса и клавиатуры, адаптировать подписку под новую сигнатуру событий.
  4. Настроить новые опции для модальных окон (trapFocus, focusRoot) для корректной работы навигации.
  5. Обновить документацию проекта с учетом новых возвращаемых структур и полей объектов.

Эти шаги позволяют сохранить доступность интерфейса и предотвратить ошибки после перехода на новую версию ally.js.

Оглавление