Подсказка

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

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

Короткое пояснение, которое нужно каждому, остаётся строкой под полем — словом Подсказка. Отказ сервера — словом Ошибка: его не прячут. Всё, без чего форму не заполнить, видно сразу.

У поля#

У поля справку печатает слово Справка(Текст) самого поля: значок «?» встаёт в строку подписи у правого края поля, поповер — под ним, а поле ссылается на текст поповера из aria-describedby. Короткая Подсказка остаётся строкой под полем. У выпадающего списка значок стоит левее шеврона, у флажка — сразу за подписью.

Значок называет себя скринридеру «Справка: Ключ проекта» — шаблон словаря help.field. Идентификатор поповера — Ид поля с хвостом -help, а без Ид кит выдаёт свой из имени и места поля: постоянный для того же дерева.

Отдельно#

Кит.Подсказка(Текст) — тот же значок с поповером где угодно: в строке текста, рядом с подписью группы. Имя значка для скринридера — слово Подпись, без него — текст словаря help.open («Справка»).

Без скрипта#

Всё работает без скрипта: значок — кнопка с атрибутом popovertarget, поповер — атрибут popover. Esc и щелчок мимо закрывают его, фокус возвращается на значок — это делает браузер. Движок, который не знает popover, печатает текст пояснения сразу за значком: он остаётся на странице.

Где встаёт поповер#

Поповер встаёт под значком; не хватит места справа или снизу — браузер отзеркалит его. Движок без привязки к якорю ставит его по центру экрана. На телефоне (до 640 px) поповер шириной в экран с полями 16 px, под значком или над ним: за край он не уходит, где бы значок ни стоял.

Гайдлайны#

HTML = Кит.Поле("key", "Ключ проекта").Подсказка("латиницей, без пробелов")
	.Справка("Ключ входит в адрес проекта и в имена его файлов. Сменить его потом нельзя.").Рендер();

HTML = Кит.Поле("key", "Ключ проекта").Подсказка("Латиницей, без пробелов. Ключ входит в адрес проекта"
	+ " и в имена его файлов. Сменить его потом нельзя: старые ссылки перестанут работать.").Рендер();

HTML = Кит.Поле("owner", "Владелец").Справка("Владелец получает письма о сбоях сборки.").Рендер();

HTML = Кит.Холст(Кит.Поле("owner", "Владелец"),
	Кит.Подсказка("Владелец получает письма о сбоях сборки.")).Рендер();

HTML = Кит.Поле("email", "Почта").Справка("Обязательно рабочая почта, иначе приглашение не дойдёт.").Рендер();

Условие, без которого форму не заполнить, пишут подсказкой под полем, а проверяет его форма.

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

• Значок — кнопка type="button": форму не отправляет. Имя у неё своё — «Справка: Ключ проекта» (aria-label), знак «?» скрыт от скринридера. Открыт ли поповер, браузер сообщает сам (aria-expanded у кнопки с popovertarget).
• Поле ссылается на текст поповера из aria-describedby: скринридер читает пояснение, когда фокус приходит в поле, и открывать поповер ему не нужно. У отбитого поля описание — отказ, потом справка.
• Значок стоит вне <label> поля: кнопка внутри метки стала бы её полем.
• Значок 24 px, а зона нажатия — 48 px. Esc закрывает поповер, фокус возвращается на значок.
• Настройка «меньше движения» гасит проявление поповера.

Модель#

Подсказка — значок «?», по нажатию на который рядом открывается поповер с пояснением:
длинный текст уходит с экрана, но остаётся в одном нажатии. Ставят рядом с заголовком
секции, подписью группы, словом в тексте. Поповер открывает и закрывает движок браузера
(атрибут popover): Esc и щелчок мимо закрывают его, фокус возвращается на значок, скрипта
нет. У поля пояснение печатает слово Справка(Текст) самого поля — оно ещё и связывает
текст с полем для скринридера. Слова: Подпись (имя значка для скринридера; по умолчанию
текст словаря «help.open»), Якорь (идентификатор поповера; без него кит выдаёт свой,
постоянный для того же дерева).

Параметры:
 Текст - Строка - пояснение (экранируется).

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

Справка поля — длинное пояснение, которое не помещается строкой под полем: значок «?»
рядом с подписью открывает поповер с текстом, а поле называет текст своим описанием
(aria-describedby) — скринридер прочтёт его, когда фокус придёт в поле. Короткое
пояснение остаётся словом Подсказка: строкой под полем.

Параметры:
 Текст - Строка - пояснение (экранируется при печати).

Возвращаемое значение:
 ЭлементЭкрана - это же поле.

Печатает значок «?» и поповер с текстом. Без текста не печатает ничего: пустой поповер
открылся бы пустым местом.

Параметры:
 Модель - Структура - Ид (идентификатор поповера: на него ссылается popovertarget),
          Текст (пояснение; экранируется), Подпись (имя кнопки для скринридера; пусто —
          текст словаря «help.open»).

Возвращаемое значение:
 Строка - <button class="help"> и <span class="help__pop" popover> подряд либо "".