Формы frontend-приложений¶
Требования этого документа применяются к browser-формам и другим интерфейсам
структурированного пользовательского ввода frontend-приложений. Уровни
обязательности определены в корневом README.md.
FE-FORM-001. Контракт поля формы¶
Уровень: MUST
Применяется к: каждому полю, значение которого передаётся в прикладную операцию
Поле должно иметь стабильное имя, тип, обязательность, допустимые границы и
семантику отсутствующего, пустого, нулевого и ложного значения,
соответствующие контракту операции. Нормализация отображения не должна
незаметно изменять передаваемое значение. Клиентская валидация должна
использовать те же границы, но не должна считаться заменой проверки на
доверенной прикладной границе; для HTTP API применяется BE-HTTP-007.
Browser-control должен публиковать label, нативный тип ввода, соответствующий
контрактному типу значения, и стандартный token autocomplete, когда такой
token определён для назначения поля. Приложение не должно запрещать paste,
password manager или autofill без отдельного security-контракта. Ошибка должна
связываться со стабильным кодом поля или формы, а не определяться разбором
локализованного текста.
Обоснование¶
Разная семантика поля в UI и API создаёт потерю значения, ложную валидацию и несовместимость с browser-инструментами ввода.
Проверка¶
- contract-тест формы и API для граничных и отсутствующих значений;
- component-тест autofill, paste и отображения ошибки;
- автоматическая проверка label, типа и
autocomplete.
Исключения¶
Визуальный control MAY использовать скрытое нативное поле, если сохраняет его семантику, доступность и фактически передаваемое значение.
FE-FORM-002. Единственный результат отправки¶
Уровень: MUST
Применяется к: отправке формы, создающей прикладной эффект
Состояние формы должно различать выполнение, подтверждённый успех, отказ
валидации, конфликт, технический отказ и неопределённый результат согласно
UI-STATE-002. Повторный submit во время выполняющейся операции не должен
создавать независимый эффект.
Если операцию разрешено повторить после неопределённого результата, повтор
должен сохранять тот же стабильный идентификатор операции, а provider —
дедуплицировать эффект; для HTTP API применяется BE-HTTP-003. Интерфейс не
должен сообщать об успехе, очищать введённые данные или переходить к следующему
необратимому шагу до подтверждения контрактного результата.
Обоснование¶
Двойной submit и новый ключ при повторе после timeout создают несколько необратимых эффектов при одном пользовательском намерении.
Проверка¶
- e2e-тест двойного submit и медленного ответа;
- тест timeout после фактического выполнения операции;
- проверка сохранения ввода при валидации, конфликте и техническом отказе.
Исключения¶
Независимые операции MAY выполняться параллельно, если интерфейс показывает отдельный результат каждой и они не используют одно состояние формы.
FE-FORM-003. Черновик и несохранённое изменение¶
Уровень: MUST
Применяется к: форме с autosave, локальным черновиком или предупреждением о несохранённых данных
Проект должен определить владельца черновика, исходную версию данных, момент сохранения, срок хранения и результат ухода со страницы. Autosave не должен показывать сохранённое состояние до подтверждения записи. Конкурентное изменение должно обнаруживаться версией или precondition и не должно молча перезаписываться черновиком.
Локально сохранённый черновик должен выполнять FE-OFF-001, быть изолирован по
субъекту и удаляться после подтверждённой отправки, явного отказа пользователя
от черновика или истечения объявленного срока.
Обоснование¶
Неопределённый lifecycle черновика приводит к потере ввода, восстановлению данных другого субъекта и перезаписи более нового состояния.
Проверка¶
- тест ухода, reload, возврата и истечения черновика;
- конкурентный тест autosave и внешнего изменения;
- тест смены пользователя и подтверждённой отправки.
Исключения¶
Форма без autosave, локального черновика и обещания восстановления находится вне области требования.