Breaking changes

Библиотека Tabbable служит для определения элементов на веб-странице, которые могут быть достигнуты с помощью клавиши Tab. С выходом новых версий появляются изменения, влияющие на совместимость с существующим кодом. Эти изменения необходимо учитывать при обновлении проекта, чтобы избежать неожиданного поведения в интерфейсе.

1. Изменения в списке определяемых tabbable элементов

Ранее Tabbable считала некоторые элементы focusable по умолчанию, даже если они были скрыты через CSS (display: none или visibility: hidden). В новых версиях библиотека стала более строгой:

  • Элементы с display: none и visibility: hidden исключаются из списка tabbable.
  • Элементы с атрибутом tabindex="-1" больше не включаются автоматически, если они не содержат активный обработчик фокуса.

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

2. Поведение tabindex и приоритет элементов

В новых версиях изменился порядок приоритета элементов:

  1. Элементы с положительным tabindex – порядок соответствует числу в атрибуте, от меньшего к большему.
  2. Элементы без tabindex или с tabindex="0" – следуют естественному порядку документа.
  3. Элементы с tabindex="-1" – исключены из стандартной табуляции.

Ранее библиотека могла интерпретировать отрицательные значения tabindex как допустимые для табуляции, что теперь исправлено.

3. Поддержка Shadow DOM

Новая версия Tabbable добавила поддержку элементов внутри Shadow DOM, но с изменениями:

  • Shadow host рассматривается как обычный контейнер, но элементы внутри shadow root учитываются только если вызывается функция с явным параметром includeShadow: true.
  • Стили скрытия внутри Shadow DOM теперь корректно учитываются, что предотвращает попадание невидимых элементов в список tabbable.

4. Обработка нестандартных элементов

Библиотека изменила подход к некоторым нестандартным элементам:

  • <details> и <summary> теперь учитываются более строго. Ранее <summary> считался tabbable всегда, сейчас tabbable только если раскрыт <details> или явно задан tabindex.
  • SVG-элементы, которые могут быть focusable (<svg>, <circle>, <rect>), теперь включаются только если явно имеют tabindex или свойства focusable="true".

Это влияет на интерфейсы с интерактивной графикой или кастомными контролами.

5. API изменения

Функции библиотеки изменились в семантике и наборе аргументов:

  • tabbable(container) – возвращает массив элементов, доступных для табуляции.

    • Раньше возвращал все focusable элементы, теперь возвращает только tabbable.

  • focusable(container) – возвращает элементы, которые могут быть сфокусированы программно, включая элементы с tabindex="-1".

  • Добавлен параметр includeShadow для поддержки Shadow DOM.

  • Методы больше не модифицируют исходный массив элементов, что предотвращает непреднамеренные side-effects при повторных вызовах.

6. Совместимость с предыдущими версиями

Из-за изменений логики определения tabbable элементов возможны следующие эффекты при обновлении:

  • Пропадание фокуса с некоторых элементов в формах и модальных окнах.
  • Нарушение ожидаемой последовательности табуляции, особенно при использовании кастомных контролов с tabindex.
  • Необходимость явного указания элементов внутри Shadow DOM или динамически созданных элементов через атрибут tabindex.

Для минимизации проблем рекомендуется:

  • Проверять порядок табуляции после обновления.
  • Использовать focusable() для элементов, которые должны оставаться доступными через скрипт.
  • Явно задавать tabindex для нестандартных интерактивных элементов и элементов внутри Shadow DOM.

7. Итоги по breaking changes

Главные направления изменений:

  • Строже фильтруются скрытые и неинтерактивные элементы.
  • Изменен порядок табуляции и приоритет элементов.
  • Shadow DOM и нестандартные элементы требуют явного управления фокусом.
  • API стал более предсказуемым, но несовместимым с некоторыми старыми сценариями.

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

Оглавление