Композитные ARIA-виджеты: паттерны APG — клавиатурные контракты

Паттерн — это карта клавиш, а не внешний вид

WAI-ARIA Authoring Practices Guide (APG) читается как книга рецептов, но на самом деле определяет набор контрактов: для каждого паттерна виджета — tabs, listbox, combobox, dialog, menu — точные роли, обязательные атрибуты состояния и точную карту клавиш. Tabs: tablist, содержащий элементы tab, aria-selected на активном, стрелки влево/вправо для перемещения, Home/End для прыжка. Listbox: listbox с элементами option, aria-selected, вверх/вниз, type-ahead. Combobox: input с role="combobox", aria-expanded, всплывающий listbox, Down открывает и ходит по списку, Escape закрывает. Контракт существует потому, что пользователи assistive technology выучивают паттерн один раз и воспроизводят его везде: когда скринридер объявляет «список вкладок», пользователь уже знает, что стрелки будут перемещать между вкладками. Реализуйте внешний вид без карты клавиш — и объявление даёт обещание, которое ваш виджет нарушает: это хуже, чем отсутствие паттерна, потому что обращает тренировку пользователя против него самого.

Структурное правило в основании каждого композитного паттерна: один Tab-стоп на виджет. Композит — список вкладок, listbox, грид, меню — это одна сущность в Tab-последовательности страницы. Tab входит в него, Tab выходит из него, стрелки ходят внутри. Диспетчерская консоль сломала ровно это: пятьдесят опций с tabIndex={0} превратили один виджет в пятьдесят Tab-стопов, и клавиатурная топология страницы стала болотом. Это правило — ещё и причина, по которой композиты вообще требуют инженерии: по умолчанию HTML вставляет каждый фокусируемый элемент в Tab-порядок, и чтобы пятьдесят сущностей вели себя как одна, нужно активно управлять тем, какой элемент фокусируем в каждый момент. Санкционированных механизмов ровно два.

Roving tabindex против aria-activedescendant

Roving tabindex держит настоящий DOM-фокус на активном элементе и двигает его стрелками. Ровно один элемент композита имеет tabIndex={0} (активный); все остальные — tabIndex={-1}. Поэтому Tab входит в композит на активном элементе. По ArrowRight: обновить состояние React, ререндер меняет пару tabindex, и вызвать focus() на DOM-узле нового активного элемента — нужен ref на каждый элемент, и вызов фокуса должен случиться после коммита (территория flushSync из прошлого урока, если ведёте от состояния). Награда: это настоящий фокус — стилизация через :focus-visible просто работает, document.activeElement говорит правду, скринридеры отслеживают его нативно.

function Tabs({ tabs, active, onSelect }) {
  const refs = useRef(new Map());
  const onKeyDown = (e) => {
    const delta = e.key === "ArrowRight" ? 1 : e.key === "ArrowLeft" ? -1 : 0;
    if (!delta) return;
    const next = (active + delta + tabs.length) % tabs.length;
    onSelect(next);
    refs.current.get(next)?.focus(); // настоящий фокус следует за состоянием
  };
  return (
    <div role="tablist" onKeyDown={onKeyDown}>
      {tabs.map((t, i) => (
        <button
          key={t.id}
          role="tab"
          aria-selected={i === active}
          tabIndex={i === active ? 0 : -1}
          ref={(el) => refs.current.set(i, el)}
        >
          {t.label}
        </button>
      ))}
    </div>
  );
}

aria-activedescendant переворачивает модель: DOM-фокус не двигается никогда. Он остаётся на контейнере (для combobox — на текстовом поле), а контейнер несёт aria-activedescendant={activeOptionId}, указывающий на визуально подсвеченный элемент. Скринридер объявляет элемент по ссылке так, будто тот в фокусе, — виртуальный фокус. Всё, что фокус давал бесплатно, вы теперь делаете сами: стилизацию подсветки (нет :focus, за который можно зацепиться), прокрутку активной опции в видимую область и стабильные уникальные id на каждой опции. Решающий случай — combobox: пользователь печатает, поэтому DOM-фокус обязан оставаться в поле ввода, пока стрелки ходят по списку подсказок, — перенос настоящего фокуса оборвал бы сессию набора. Roving tabindex физически не умеет выразить «фокус здесь, подсветка там»; activedescendant существует ровно для этого расщепления.

Таблица компромиссов: roving tabindex даёт настоящие события фокуса, бесплатную стилизацию фокуса и платформенную прокрутку при фокусировке — ценой ререндера плюс вызова focus() на каждое нажатие стрелки и сантехники с ref. Activedescendant даёт неподвижный фокус (обязательно для полей с набором текста, дешевле на нажатие — одна смена атрибута) — ценой самодельной подсветки, самодельной прокрутки, дисциплины id и исторически менее однородной поддержки в AT, почему сам APG применяет его главным образом там, где он структурно необходим. По умолчанию — roving tabindex для tabs, меню, радиогрупп, тулбаров; activedescendant — когда фокус должен стоять на месте: combobox, поиск с подсказками, командная палитра.

ARIA не должна лгать, и когда покупать вместо строить

Каждый атрибут состояния в контракте — aria-expanded, aria-selected, aria-activedescendant, aria-checked — обязан выводиться из того же состояния React, что управляет пикселями. Строковый литерал aria-expanded="false" диспетчерской консоли — каноническая ложь: рендер попапа зависел от open, атрибут — нет, и две истины разошлись на первом же клике. В JSX исправление механическое — aria-expanded={open} (React сериализует булево в строку, которую ждёт AT), — но дисциплина архитектурная: одна переменная состояния, две проекции (пиксели и ARIA), ноль синхронизируемых вручную копий. Виджет, у которого визуальное состояние расходится с объявленным, хуже неподписанного div, потому что пользователи AT действуют по объявлению: «свёрнуто» означает «нажми Enter, чтобы открыть», а Enter на уже открытом combobox его закрывает — пользователь и виджет теперь расходятся в картине реальности, и каждое следующее нажатие усугубляет ошибку.

Итак: строить или покупать? Честная калькуляция combobox, построенного по контракту APG: полная карта клавиш (type-ahead по печатным символам, Down/Up/Home/End/Escape/Enter, вариации Alt+Down), проводка activedescendant, управление прокруткой, дисциплина id, восстановление фокуса при закрытии — и затем статья, которую никто не закладывает в бюджет: верификация по матрице AT (NVDA и JAWS на Windows, VoiceOver на macOS и iOS, TalkBack на Android, каждый на двух-трёх браузерах). Это недели работы специалиста на один виджет, и это объясняет существование headless-библиотек компонентов: Radix UI, React Aria, Headless UI поставляют контракт — роли, атрибуты состояния, карты клавиш, управление фокусом — с нулём визуальных мнений, оставляя стилизацию вам. Сеньорское решение асимметрично: берите библиотеку для combobox, select, menu, dialog и date picker — паттернов, где контракт глубок и матрица AT беспощадна; стройте руками мелкие — tabs разумен как первая самостоятельная сборка, disclosure тем более, — когда нужно владеть паттерном или цена зависимости неоправданна. Честные издержки покупки: зависимость, которую надо обновлять, мнения библиотеки о композиции в вашем API компонентов и вес бандла; честная издержка стройки: весь контракт выше, навсегда, включая каждую регрессию связки браузер-AT, вышедшую после вас.