specs/openspec/specs/frontend-platform/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 переходить
в спокойное локализованное состояние недоступности без технических подробностей
и ручного повтора, пока автоматические повторы не исчерпаны (далее по
`frontend-data-resilience`). Это состояние 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** состояние недоступности ограничено этим блоком и не заменяет доступное содержимое страницы