GrImageViewer

urlList принимает оба варианта, в том числе вперемешку:

<GrImageViewer
  v-model="open"
  :url-list="[
    { src: '/photos/roof.jpg', alt: 'Крыша с высоты' },
    '/photos/plan.png',
  ]"
/>

Строка задаёт только адрес — alt у такого кадра пустой. Придумать текст за потребителя компонент не может, но и молча подставлять имя файла не должен: для незрячего пользователя «roof.jpg» не описание. Объектная форма — способ дать описание там, где оно есть.

alt приходит и в слот тулбара (src, alt в slot-props) — тулбар может показать подпись рядом с кадром.

Слой объявляет себя диалогом, поэтому у него всегда есть имя: из локали (gr.imageViewer.label) или из пропа ariaLabel. Диалог без имени — нарушение aria-dialog-name.

Смена кадра уходит в общий живой регион пакета (announcer.md): «Изображение 2 из 5» (gr.imageViewer.position). При открытии позиция не объявляется — её скажет имя диалога.

Регион лежит вне просмотрщика, хотя тот накрывает страницу inert. Это работает благодаря пропуску по data-gr-live-region в стеке слоёв: inert выбрасывает поддерево из дерева доступности, и регион внутри него замолчал бы.

Счётчик showProgress остаётся чисто визуальным: он дублирует ту же информацию глазами.

Колесо и жест трекпада увеличивают в точку под курсором, а не от центра: иначе до нужного угла увеличенного кадра пришлось бы добираться отдельным перетаскиванием.

Смещение кадра ограничено его собственным переполнением — насколько картинка вылезла за область просмотра, настолько её и можно тянуть. Утащить изображение в пустоту и потерять его нельзя, а при возврате к масштабу 1 смещение обнуляется само. Поворот на 90° меняет оси местами, и границы считаются по повёрнутому кадру.

Тянуть увеличенный кадр можно всегда — проп draggable разрешает перетаскивание и на вписанном (актуально для повёрнутых кадров, которые вылезают за экран и без зума).

У жестов два владельца, и это видно в поведении. Мышь и перо ведёт общий примитив useDragGesture: слушатели на window, поэтому отпускание ловится и за пределами картинки, и когда кадр сменился прямо посреди жеста. Касание ведёт свой трекер — у него многопальцевая модель: pinch двумя пальцами, свайп для листания, а на увеличенном кадре одиночный жест тянет.

Обрыв жеста (браузер забрал указатель — системный жест, звонок, потеря окна) заканчивает перетаскивание, оставляя кадр там, куда его довели, и не засчитывается как свайп: прерванный жест не листает.

Номинальный масштаб против реального

scale номинальный: единица — это «кадр вписан в окно» (object-contain), а не натуральный размер. У фотографии 4752 px, вписанной в окно шириной ~1000 px, номинальные 100% — это реальные 21%: пикселей на таком масштабе не видно вовсе.

Отсюда две разные кнопки тулбара. «100%» сбрасывает трансформацию и возвращает вписанный кадр; «1:1» (actions.zoomToNatural) доводит до реальных 100% — пиксель картинки на пиксель экрана. Считать это потребителю самому не нужно, хотя данные для расчёта слот отдаёт (naturalWidth, renderedWidth, realScale).

Потолок maxScale действует и на «1:1»: он ограничивает зум сознательно, и натуральный размер — не повод его обойти. Дефолтные maxScale: 5 для крупного кадра до реальных 100% не дотягивают (нужное номинальное приближение — это naturalWidth / renderedWidth при scale = 1, у фотографий это 5–12×), поэтому крупным изображениям потолок задаётся пропом. Обратное тоже работает: если кадр меньше своего места на экране, «1:1» уменьшит его — с оглядкой на minScale.

Сенсорные жесты работают на тех же pointer-событиях:

Порог свайпа — 60px и преобладание горизонтали: вертикальное движение листать не должно, пользователь целился не туда. Картинка объявлена touch-action: none, иначе браузер забирает жест себе и уводит страницу вместо зума.

showDownload добавляет в тулбар кнопку: она скачивает текущий кадр (<a download>) и эмитит download с { src, alt, index } — для аналитики.

Кросс-доменный адрес браузер скачает не всегда: атрибут download для чужого источника игнорируется, и файл откроется в новой вкладке. Там, где нужны подписанные ссылки или свой запрос, кнопку выключают (showDownload: false) и кладут свою в слот #toolbar-actions — он получает те же slot-props, включая actions.download.

Соседи текущего кадра греются только у открытого просмотрщика: закрытый на странице не тянет два полноразмерных изображения просто потому, что он там есть. При смене кадра и при закрытии незавершённые загрузки обрываются — иначе быстрое перелистывание галереи копит запросы, которые уже никому не нужны.

Просмотрщик держится за кадр, а не за индекс. Догрузилась следующая страница галереи — открытое изображение остаётся на экране вместе с масштабом и поворотом, даже если по позиции оно сдвинулось. Пропал текущий кадр из списка — индекс приводится к границам, а не к initialIndex: выбрасывать пользователя на первое изображение при каждой подгрузке нельзя.

--gr-z-modal, как у остальных модальных оверлеев. zIndexVar подменяет переменную слоя своей — тот же escape-hatch, что у useFloating и GrLoading. Сырого числа компонент не принимает: слой задаётся шкалой, см. ../z-index.md.

Точное значение — calc(var(<токен>) + глубина): свою глубину среди открытых модальных слоёв просмотрщик берёт из стека, поэтому поверх окна он оказывается и по отрисовке, а не только по Esc. С zIndexVar это работает так же — глубина прибавляется к подменённой переменной.

Esc, inert для нижних слоёв и возврат фокуса идут через общий стек (useOverlayLayer), поэтому просмотрщик поверх модалки закрывает себя, а не её.

Панель, кнопки и подложка красятся покомпонентными токенами:

Значения одинаковы в светлой и тёмной теме намеренно: рядом с фотографией светлая панель спорит с содержимым и подсвечивает края кадра. Токены нужны не для смены темы, а чтобы потребитель мог перекрасить хром под свой продукт.

<GrImageViewer ref="viewer" v-model="open" :url-list="images" />

viewer.value отдаёт close, prev, next, zoomIn, zoomOut, zoomToNatural, reset, rotateLeft, rotateRight — тот же набор, что получает слот тулбара. Открытия среди них нет: оно принадлежит v-model, вторая точка входа рассинхронизировала бы состояние с моделью.