@boobooking/dashboard-ui-components 0.17.0 → 0.18.0

package/README.md

@@ -90,9 +90,9 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 
 ## Компоненты
 
-Пакет экспортирует семнадцать компонентов: `Dot`, `RussianMobileFilter`,
+Пакет экспортирует восемнадцать компонентов: `Dot`, `RussianMobileFilter`,
 `Search`, `SelectDateInterval`, `SelectSingle`, `InfoPill`,
-`ErrorMessages`, `ActionPill`, `ConfirmationModal`,
+`ErrorMessages`, `FormInput`, `ActionPill`, `ConfirmationModal`,
 `DropdownButtonWithAction`, `HamburgerMenu`, `DataTable`,
 `NavigationMenuElement`, `PageTabs`, `PageCard`, `NotificationMessage`,
 `TextPopover`, функцию `downloadFile` и плагин `dashboardUi`. В архив пакета
@@ -164,6 +164,65 @@ Enter, пробелом, расширением клавиатурной нав
 изменённое родителем, поле показывает сразу и без событий: ответный
 `update:modelValue` вернул бы родителю его же значение.
 
+### FormInput
+
+Поле формы с подписью над ним. Значение забирает форма: у поля нет
+события `changed`.
+
+    <form-input v-model="name" label="Имя" :is-required="markNameRequired" />
+    <form-input v-model="email" label="Email" type="email" :is-required="markEmailRequired" />
+    <form-input v-model="password" label="Пароль" type="password" :is-required="markPasswordRequired" />
+
+| Проп | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `modelValue` | `String` | `""` | Значение поля |
+| `label` | `String` | обязателен | Подпись над полем |
+| `type` | `String` | `"text"` | `"text"`, `"email"`, `"password"`, `"tel"`, `"url"` или `"search"` |
+| `isRequired` | `Boolean` | `false` | Красная точка у подписи |
+
+Событие `update:modelValue` уходит на каждый ввод со строкой из поля как
+есть: пробелы не обрезаются, это решение формы. Исключение — `type="email"`
+и `type="url"`: браузер сам убирает пробелы по краям значения, и Email из
+одних пробелов приходит пустой строкой. Формы, которые проверяют
+`length > 0`, оставляют у Email `type="text"`. Значение, изменённое
+родителем, поле показывает сразу и без события. Набор через IME
+(composition) отдаёт значение по его окончании.
+
+Используйте `v-model` без модификаторов: модификаторы (`.trim`, `.number`,
+`.lazy`) не входят в API `FormInput`; пробелы форма обрезает сама при
+отправке.
+
+Другой `type`, не из списка, отклоняется предупреждением Vue, а поле
+рисуется с `type="text"`.
+
+`class` и `style` ложатся на корень компонента, все остальные атрибуты
+и слушатели (`autocomplete`, `placeholder`, `name`, `disabled`, `@blur`,
+`@keydown.enter`) — на `<input>`. `id` поля создаётся сам, `for` подписи
+указывает на него, поэтому две копии на странице не делят один `id`.
+Атрибут `id` от формы заменяет созданный и в поле, и в `for`.
+
+Красная точка значит «не заполнено»; когда её показывать, решает форма.
+Основной способ: точки появляются после попытки отправить, ввод в поле
+снимает свою, а стирание поля ставит точку снова (так делает watcher
+из примера).
+
+    watch: {
+        name() { this.markNameRequired = this.name.length === 0 },
+    },
+    methods: {
+        create() {
+            this.markNameRequired = this.name.length === 0
+            // то же для остальных полей
+        },
+    },
+
+Способ «сразу», точка видна, пока поле пусто:
+
+    <form-input v-model="number" label="Номер" :is-required="number.trim() === ''" />
+
+`isRequired` только показывает точку: атрибут `required` и `aria-*` полю
+он не ставит.
+
 ### SelectDateInterval
 
 Два поля даты под одним заголовком — интервал дат «от» и «до». Дата
@@ -396,8 +455,8 @@ exportOrders() {
 | `lang` | `String` | язык плагина | `"ru"` или `"en"` |
 
 События: `actionConfirmed` — по кнопке действия, `actionCanceled` — по кнопке
-отмены. Ни одна из кнопок модалку не закрывает — см. раздел «Почему у
-ConfirmationModal нет v-model».
+отмены и по Escape. Ни одна из кнопок модалку не закрывает — см. раздел
+«Почему у ConfirmationModal нет v-model».
 
 Панель модалки — белая, со скруглением `rounded-lg`, стоит по центру и
 занимает `max-w-lg`. `class` и другие атрибуты на `<confirmation-modal>`
@@ -405,6 +464,13 @@ ConfirmationModal нет v-model».
 содержимое, поэтому блоки текста и кнопок со своим фоном скругляют внешние
 углы сами — верхний `rounded-t-lg`, нижний `rounded-b-lg`.
 
+Открытая модалка держит фокус: в первом кадре после открытия он встаёт на
+кнопку отмены, Tab и Shift+Tab ходят по её кнопкам по кругу, Escape —
+`actionCanceled`, как кнопка отмены. После закрытия фокус возвращается туда,
+где был до открытия, если страница не поставила его в другое место и тот
+элемент ещё на странице. Кадр нужен модалкам, которые открывает пункт меню:
+меню закрывается позже в том же клике и возвращает фокус на свою кнопку.
+
 ### DropdownButtonWithAction
 
 Кнопка из списка действий `actions`. Первое действие — основная кнопка,
@@ -978,9 +1044,9 @@ Inertia SSR), а серверная разметка гидратируется
 Правило пакета — значение через `v-model` — относится к состоянию, которое
 компонент меняет сам: меню `DropdownButtonWithAction` закрывается по клику
 вне, `SelectSingle` меняет выбор. `ConfirmationModal` свою видимость не меняет
-никогда. Обе кнопки только сообщают родителю решение пользователя, а закрыть
-модалку, оставить её открытой на время запроса или открыть следующую — решает
-родитель.
+никогда. Обе кнопки и Escape только сообщают родителю решение пользователя,
+а закрыть модалку, оставить её открытой на время запроса или открыть
+следующую — решает родитель.
 
 `v-model` обещал бы двустороннюю связь, которой нет, поэтому видимость
 передаётся пропом `isOpen`.
@@ -999,7 +1065,7 @@ Inertia SSR), а серверная разметка гидратируется
 
     npm run playground
 
-Поднимает демо-страницы со всеми семнадцатью компонентами в двух окружениях:
+Поднимает демо-страницы со всеми восемнадцатью компонентами в двух окружениях:
 голом (без Tailwind и стилей приложения) и в окружении приложения (с
 Tailwind, `@tailwindcss/forms` и типографикой, как у потребителя). Это
 основной способ посмотреть, как компоненты выглядят и ведут себя, а не
@@ -1300,7 +1366,3 @@ exportOrders() {
 Например, чекбоксу: `border border-gray-300 bg-white text-indigo-600
 checked:bg-current checked:border-transparent focus:ring-2
 focus:ring-offset-2`.
-
-`ConfirmationModal` не переносит фокус внутрь при открытии, не удерживает его
-внутри, не возвращает на прежнее место после закрытия и не закрывается по
-Escape.