specs/openspec/specs/frontend-loading-presentation/spec.md

frontend-loading-presentation Specification

Purpose

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

Requirements

Requirement: Структурные placeholders для загрузки содержимого

Frontend SHALL при первичной загрузке содержимого без доступного результата показывать skeleton placeholders, которые передают расположение и визуальную иерархию основных ожидаемых блоков. При частичной загрузке frontend MUST ограничивать skeleton незагруженным блоком и сохранять уже доступные части экрана видимыми. В этих состояниях frontend MUST NOT использовать отдельный spinner как основное представление ожидаемого содержимого.

Skeleton placeholders MUST NOT содержать правдоподобные пользовательские данные, быть интерактивными или попадать в последовательность клавиатурного фокуса; область ожидания MUST оставаться доступно обозначенной как занятая.

Scenario: Экран впервые ожидает содержимое

• WHEN User открывает экран, для которого ещё нет доступного результата
• THEN frontend показывает структурные skeleton placeholders основных блоков без отдельного spinner в роли основного loading-состояния

Scenario: Загружается отдельный блок экрана

• WHEN часть экрана уже доступна, а один из его содержательных блоков всё ещё ожидает результат
• THEN frontend сохраняет доступные части видимыми и показывает skeleton только в границах ожидающего блока

Scenario: Пользователь перемещает клавиатурный фокус во время загрузки

• WHEN на экране видны skeleton placeholders и User перемещает клавиатурный фокус
• THEN placeholders не получают фокус и не воспринимаются как доступные действия или реальные пользовательские данные

Requirement: Представление загрузки маршрута и восстановления сессии

Frontend SHALL во время загрузки отложенно открываемого маршрута показывать skeleton ожидаемой области содержимого, сохраняя уже доступный каркас приложения. Во время начального восстановления пользовательской сессии frontend MUST показывать нейтральный skeleton каркаса до определения доступного пользователю потока и MUST NOT кратковременно показывать содержимое public или protected маршрута как результат загрузки. В обоих случаях отдельный spinner MUST NOT быть основным loading-состоянием.

Scenario: Загружается отложенно открываемый маршрут

• WHEN User переходит на маршрут, содержимое которого ещё загружается
• THEN frontend сохраняет доступный каркас приложения и показывает skeleton в ожидаемой области содержимого без отдельного spinner в роли основного loading-состояния

Scenario: Приложение восстанавливает сессию при запуске

• WHEN frontend ещё не определил результат начального восстановления пользовательской сессии
• THEN User видит нейтральный skeleton каркаса без преждевременного отображения public или protected содержимого

Requirement: Контекстная индикация действий и фонового обновления

Frontend MUST сохранять уже доступное содержимое или элемент управления основным контекстом, когда выполняется пользовательское действие либо фоновое обновление Client Cached Snapshot. Явное действие пользователя SHALL иметь компактную индикацию ожидания рядом с соответствующим элементом управления. Фоновое обновление при доступном результате MUST проходить без индикаторов, технических сообщений и объявлений о ходе работы. В обоих случаях frontend MUST NOT заменять уже доступный контекст skeleton placeholders.

Scenario: Выполняется пользовательское действие

• WHEN User запустил действие и его результат ещё ожидается
• THEN frontend сохраняет соответствующий элемент управления или окружающий контекст видимым, показывает компактную индикацию процесса и не заменяет интерфейс skeleton placeholders

Scenario: Обновляется уже показанный snapshot

• WHEN frontend обновляет данные при наличии видимого Client Cached Snapshot
• THEN frontend оставляет snapshot видимым без индикации фонового обновления и без замены snapshot skeleton placeholders

Requirement: Первичное ожидание не становится бесконечной загрузкой

При отсутствии результата frontend SHALL сначала показывать структурное ожидание соответствующей области. После неуспешного завершения получения либо истечения ограниченного времени первичного ожидания область MUST переходить в спокойное локализованное состояние недоступности без технических подробностей и ручного повтора. Это состояние MUST NOT утверждать, что результат пустой, или требовать перезагрузки страницы. Продолжающееся автоматическое восстановление MUST NOT заставлять область постоянно переключаться между недоступностью и skeleton. После успешного получения содержимое SHALL появляться автоматически.

Отсутствие результата одной области MUST NOT скрывать остальные доступные области. Первичная загрузка MUST сохранять доступное обозначение занятости, а состояние недоступности MUST NOT продолжать объявляться бесконечно занятым.

Scenario: Первый результат успешно получен

• WHEN экран ожидает первый результат и получает его в пределах первоначального ожидания
• THEN структурные placeholders сменяются содержимым либо подтверждённым пустым состоянием

Scenario: Первое получение данных не удалось

• WHEN у области нет результата и первоначальная загрузка завершилась ошибкой или превысила ограниченное время ожидания
• THEN область показывает нейтральную недоступность без кнопки повтора, вымышленных данных и бесконечного индикатора занятости

Scenario: Восстановление продолжается после недоступности

• WHEN область уже показывает недоступность и выполняется очередная разрешённая попытка восстановления
• THEN область сохраняет устойчивое состояние без мигания skeleton и автоматически показывает содержимое после успеха

Scenario: Один блок недоступен

• WHEN основной результат загружен, а дополнительный блок не получил данных
• THEN состояние недоступности ограничено этим блоком и не заменяет доступное содержимое страницы