Шаги — oscript-ui

Шаги ведут длинную форму по одному экрану за раз: сверху полоса номеров, под ней поля текущего шага, внизу «Назад» и «Дальше», на последнем шаге — отправка. «Дальше» проверяет только поля текущего шага: человек узнаёт о пустом обязательном поле там, где его заполняют, а не в конце формы.

Когда использовать#

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

Не делите на шаги короткую форму: три поля на одном экране заполнить быстрее, чем пройти три экрана. Длинной форме, которую читают целиком, хватит разделов — Кит.Группа(…).Вид("раздел"). Шаги первой настройки, которые живут на разных страницах, показывает проводник.

Мастер#

Шаги — дети узла Кит.Шаги, каждый Кит.Шаг(Подпись, поля…). Шаги кладут в форму: кнопку отправки печатают они сами, её подпись — словом Кнопка. Попробуйте нажать «Дальше» с пустым названием — браузер покажет отказ у поля, и шаг не сменится.

Новый проект за три шага

HTML = Кит.Форма("/проекты",
	Кит.Шаги(
		Кит.Шаг("Проект",
			Кит.Поле("name", "Название").Обязательное().Подсказка("латиницей, без пробелов"),
			Кит.Поле("about", "Описание").Многострочное()),
		Кит.Шаг("Участники",
			Кит.Поле("owner", "Владелец").ТипЗначения("email").Обязательное(),
			Кит.Поле("team", "Команда").Вариант("", "без команды").Вариант("core", "Ядро")),
		Кит.Шаг("Проверка",
			Кит.Примечание("Проект появится в списке сразу после создания."),
			Кит.Поле("public", "Открыть проект всем").ТипЗначения(Тип("Булево"))))
		.Кнопка("Создать проект")).Токен("т0кен-сессии").Рендер();

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

Без скрипта#

Без скрипта шаги — панели подряд (раскрывашки), открыт первый шаг, кнопка отправки под ними: форма видна и уходит целиком, а проверяет её сервер. Полоса номеров и «Назад / Дальше» печатаются спрятанными (hidden) — их показывает скрипт кита вместе с одной панелью за раз.

Отказ сервера#

Сервер, вернувший форму с отказом, ничего не говорит шагам: они сами открывают первый шаг, где у поля есть Ошибка, — и без скрипта, и со скриптом. Без отказа начинается шаг, помеченный словом Текущий(), без пометки — первый.

Вернулась с отказом во втором шаге

HTML = Кит.Форма("/проекты",
	Кит.Шаги(
		Кит.Шаг("Проект", Кит.Поле("name", "Название").Значение("альфа")),
		Кит.Шаг("Участники",
			Кит.Поле("owner", "Владелец").Значение("анна@").Ошибка("Адрес почты без домена")),
		Кит.Шаг("Проверка", Кит.Примечание("Проверьте и создайте проект.")))
		.Кнопка("Создать проект")).Токен("т0кен-сессии").Рендер();

Шаг, снятый словом Когда(Ложь), уходит вместе со своим номером: счёт идёт без дыр.

Вид «вкладки»#

Правка уже заполненного: шаги — вкладки, любая открывается сразу, без «Назад / Дальше», отправка видна всегда. Если поле, которое не пускает отправку, лежит на другой вкладке, скрипт открывает её и показывает отказ у поля.

Правка проекта

HTML = Кит.Форма("/проекты/альфа",
	Кит.Шаги(
		Кит.Шаг("Проект", Кит.Поле("name", "Название").Значение("альфа").Обязательное()),
		Кит.Шаг("Участники", Кит.Поле("owner", "Владелец").Значение("anna@example.com")),
		Кит.Шаг("Доступ", Кит.Поле("public", "Открыть проект всем").ТипЗначения(Тип("Булево"))))
		.Вид("вкладки").Кнопка("Сохранить")).Токен("т0кен-сессии").Рендер();

Кнопка отправки#

Кнопка(Подпись) — основная кнопка с этой подписью; узел Кит.Кнопка(…) печатается как есть, с его вариантом, именем и значением. Без слова — основная кнопка с текстом словаря steps.submit. Подписи «Назад» и «Дальше» — ключи словаря steps.back и steps.next.

Кнопка узлом

HTML = Кит.Форма("/участники",
	Кит.Шаги(
		Кит.Шаг("Кого", Кит.Поле("email", "Почта").ТипЗначения("email").Обязательное()),
		Кит.Шаг("Куда", Кит.Поле("project", "Проект").Вариант("alpha", "альфа").Вариант("beta", "бета")))
		.Кнопка(Кит.Кнопка("Пригласить").Основная().Иконка("конверт").Имя("do", "invite")))
	.Токен("т0кен-сессии").Рендер();

В окне#

Мастер помещается и в окно — окно-форму со словом Форма. Со словом окна АдресЗакрытия (дев-сборка 8) «Отмена» ссылкой встаёт первой в ряд кнопок шагов, слева: без скрипта она ведёт на страницу без окна, со скриптом закрывает окно. Окно с шагами шире базового (Широкое()), а на телефоне встаёт листом во весь экран: шагам мастера тесно в окне по центру, и «Дальше» должно быть под пальцем.

Мастер в окне — на телефоне во весь экран

Окно = Кит.Окно("Новый проект",
		Кит.Шаги(
			Кит.Шаг("Проект", Кит.Поле("name", "Название").Обязательное()),
			Кит.Шаг("Участники", Кит.Поле("owner", "Владелец").ТипЗначения("email")))
			.Кнопка("Создать проект"))
	.Форма("/проекты").Широкое().Якорь("master-v-okne");
HTML = Кит.Холст(Кит.Кнопка("Новый проект").Иконка("плюс").Открывает(Окно), Окно)
	.Токен("т0кен-сессии").Рендер();

Гайдлайны#

ДелайтеШаг — одна мысль, подпись — одно-два слова

Код

HTML = Кит.Форма("/проекты",
	Кит.Шаги(
		Кит.Шаг("Проект", Кит.Поле("name", "Название").Обязательное()),
		Кит.Шаг("Участники", Кит.Поле("owner", "Владелец").Обязательное()),
		Кит.Шаг("Проверка", Кит.Примечание("Всё готово."))).Кнопка("Создать")).Токен("т").Рендер();

Не делайтеШаг на каждое поле: экранов больше, чем мыслей

Код

HTML = Кит.Форма("/проекты",
	Кит.Шаги(
		Кит.Шаг("Название", Кит.Поле("name", "Название")),
		Кит.Шаг("Описание", Кит.Поле("about", "Описание")),
		Кит.Шаг("Владелец", Кит.Поле("owner", "Владелец")),
		Кит.Шаг("Команда", Кит.Поле("team", "Команда")),
		Кит.Шаг("Доступ", Кит.Поле("public", "Открыть всем").ТипЗначения(Тип("Булево")))))
	.Токен("т").Рендер();

ДелайтеОбязательное поле объявлено: «Дальше» проверит его на месте

Код

HTML = Кит.Форма("/проекты",
	Кит.Шаги(
		Кит.Шаг("Проект", Кит.Поле("name", "Название").Обязательное()),
		Кит.Шаг("Проверка", Кит.Примечание("Всё готово."))).Кнопка("Создать")).Токен("т").Рендер();

Обзор

Сводка проекта.

История

Изменения проекта.

Не делайтеШаги вместо вкладок страницы: у каждого вида объекта свой адрес

Код

HTML = Кит.Шаги(
	Кит.Шаг("Обзор", Кит.Примечание("Сводка проекта.")),
	Кит.Шаг("История", Кит.Примечание("Изменения проекта."))).Вид("вкладки").Рендер();

Соседние виды одного объекта переключают вкладки — у каждого свой адрес, его можно прислать ссылкой. Шаги — части одной формы.

Доступность#

Полоса номеров — нумерованный список: скринридер читает «список, 3 пункта». Номер и галка скрыты от него (aria-hidden), порядок называет сам список; текущий шаг помечен aria-current="step".
Панель шага называет себя «Шаг 2 из 3: Участники» (aria-label, шаблон словаря steps.progress). На неё скрипт ставит фокус, когда меняет шаг, — скринридер слышит, куда человек пришёл, а Tab ведёт к первому полю шага.
Отказ «Дальше» — родной отказ браузера у поля (reportValidity): его читает скринридер, и фокус уходит на поле.
До 640 px подписи шагов, кроме текущего, уходят из вида, но не из речи: скринридер по-прежнему читает их у кнопок полосы.
«Назад» и «Дальше» — кнопки type="button": форму не отправляют. Настройка «меньше движения» гасит прокрутку к шагам и переходы полосы.

Модель#

Кит.Шаги()src/Классы/холст/Кит.os

Шаги — длинная форма по одному экрану за раз: полоса номеров сверху (текущий залит,
пройденные с галкой), панель шага, «Назад / Дальше» и отправка на последнем шаге.
«Дальше» пускает дальше, только когда поля текущего шага годны: скрипт кита зовёт
у них reportValidity. Без скрипта шаги — панели подряд (раскрывашки), открыт первый,
кнопка отправки под ними: форма уходит целиком, проверяет её сервер. Шаги кладут
в форму. Открыт сначала шаг, где у поля есть Ошибка, иначе помеченный Текущий(), иначе
первый. Вид словом: «вкладки» (правка: любой шаг открывается сразу, без «Назад /
Дальше», отправка видна всегда) | "" (мастер). Слова: Кнопка(Подпись | узел кнопки)
— кнопка отправки (по умолчанию — основная с текстом словаря «steps.submit»), Подпись
— имя полосы номеров для скринридера.

Параметры:
Р1…Р8 - ЭлементЭкрана - (необязательные) шаги, узлы Кит.Шаг.

Возвращаемое значение:
ЭлементЭкрана

Кит.Шаг()src/Классы/холст/Кит.os

Шаг — панель Кит.Шаги: подпись называет его в полосе номеров, дети — поля шага.
Печатается только внутри Кит.Шаги. Слова: Текущий() — шаг, с которого начать (форма,
вернувшаяся на второй шаг); Когда(Ложь) снимает шаг вместе с его номером.

Параметры:
 Подпись - Строка - название шага, коротко: «Проект», «Участники».
 Р1…Р8   - ЭлементЭкрана, Строка - (необязательные) поля и текст шага; строка — текст.

Возвращаемое значение:
 ЭлементЭкрана

Шаги.Отрисовать()src/Классы/холст/Шаги.os

Печатает шаги формы: полосу номеров (её показывает скрипт), панели шагов и ряд кнопок.
Без шагов не печатает ничего.

Параметры:
 Модель - Структура - Атрибуты (ДОВЕРЕННАЯ строка атрибутов корня: класс, id, data-*),
          Вид ("" — мастер: «Назад / Дальше», отправка на последнем шаге | "вкладки" —
          правка: любой шаг открывается сразу, отправка видна всегда), Подпись (имя
          полосы номеров для скринридера; пусто — без имени), Начало (номер шага с 1,
          который открыт без скрипта и с которого скрипт начинает), Кнопка (модель
          кнопки отправки; без неё — основная кнопка с текстом словаря «steps.submit»),
          Шаги (массив структур: Подпись, Тело — ДОВЕРЕННЫЙ HTML панели, Атрибуты —
          ДОВЕРЕННАЯ строка атрибутов панели), Отмена (дев-сборка 8; ДОВЕРЕННЫЙ HTML
          ссылки-кнопки «Отмена» окна шагами — первой в ряду кнопок; пусто — её нет).

Возвращаемое значение:
 Строка - <div class="steps"> с полосой, панелями и рядом кнопок либо "".