@boobooking/dashboard-ui-components 0.17.1 → 0.19.0

package/README.md

@@ -65,10 +65,10 @@ Vue не ниже 3.5, ESM, сборщик, умеющий импорт CSS из
 Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в CSS приложения
 пакету не нужны.
 
-Меню `DropdownButtonWithAction` и `HamburgerMenu`, список `SelectSingle`,
+Меню `DropdownButtonWithAction` и `HamburgerMenu`, списки `SelectSingle` и `SelectMultiple`,
 календари `SelectDateInterval` и подсказка `TextPopover` стоят на Popover API
 браузера: Safari 17+, Chrome 114+, Firefox 125+. В браузерах старше меню,
-список, календари и подсказка видны в потоке всегда.
+списки, календари и подсказка видны в потоке всегда.
 
 ## Цвета
 
@@ -90,22 +90,24 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 
 ## Компоненты
 
-Пакет экспортирует семнадцать компонентов: `Dot`, `RussianMobileFilter`,
-`Search`, `SelectDateInterval`, `SelectSingle`, `InfoPill`,
-`ErrorMessages`, `ActionPill`, `ConfirmationModal`,
+Пакет экспортирует девятнадцать компонентов: `Dot`, `RussianMobileFilter`,
+`Search`, `SelectDateInterval`, `SelectSingle`, `SelectMultiple`, `InfoPill`,
+`ErrorMessages`, `FormInput`, `ActionPill`, `ConfirmationModal`,
 `DropdownButtonWithAction`, `HamburgerMenu`, `DataTable`,
 `NavigationMenuElement`, `PageTabs`, `PageCard`, `NotificationMessage`,
 `TextPopover`, функцию `downloadFile` и плагин `dashboardUi`. В архив пакета
 (`files: ["dist"]`) исходники не попадают, поэтому контракт каждого
 компонента — здесь и в playground, а не в исходном коде.
 
-Крестики — закрытие `PageCard` и ластики очистки фильтров — при нажатии
-коротко «вдавливаются», и действие выполняется после этого, через 150 мс:
-иначе нажатия не было бы видно — ластик пропадает сразу после очистки,
-крестик уводит со страницы. Так при любом нажатии: мышью, касанием,
-Enter, пробелом, расширением клавиатурной навигации. Нажатия во время
-анимации не считаются: одно нажатие — одно действие. При «уменьшении
-движения» в системе — без анимации и сразу.
+Ластики очистки фильтров идут в порядке Tab сразу после своего поля или
+кнопки, в фокусе с клавиатуры вокруг крестика кольцо; нажимаются Enter и
+пробелом. Крестики — закрытие `PageCard` и ластики очистки фильтров —
+при нажатии коротко «вдавливаются», и действие выполняется после этого,
+через 150 мс: иначе нажатия не было бы видно — ластик пропадает сразу
+после очистки, крестик уводит со страницы. Так при любом нажатии: мышью,
+касанием, Enter, пробелом, расширением клавиатурной навигации. Нажатия
+во время анимации не считаются: одно нажатие — одно действие. При
+«уменьшении движения» в системе — без анимации и сразу.
 
 ### Dot
 
@@ -164,6 +166,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
 
 Два поля даты под одним заголовком — интервал дат «от» и «до». Дата
@@ -204,13 +265,14 @@ Enter, пробелом, расширением клавиатурной нав
 под курсором, поэтому календарь «до» открывается тем же кликом, что
 закрывает «от».
 
-С клавиатуры: Enter или пробел на поле открывают календарь. Пока он открыт,
-стрелки переводят фокус по дням: влево и вправо — на день, вверх и вниз — на
-неделю; с края месяца календарь листается, дата при этом не выбирается.
-Первая стрелка ставит фокус на выбранный день, без выбранного — на сегодня.
-Enter или пробел выбирают день под фокусом и стрелки месяцев — так же, как
-клик; Escape закрывает календарь. После закрытия фокус возвращается на поле.
-В поле можно перейти Tab и набрать дату.
+С клавиатуры: в поле даты стрелка вниз, Enter и пробел открывают календарь.
+Кнопки календаря и списков в фокусе с клавиатуры обведены кольцом пакета. Пока
+календарь открыт, стрелки переводят фокус по дням: влево и вправо — на день,
+вверх и вниз — на неделю; с края месяца календарь листается, дата при этом не
+выбирается. Первая стрелка ставит фокус на выбранный день, без выбранного — на
+сегодня. Enter или пробел выбирают день под фокусом и стрелки месяцев — так
+же, как клик; Escape закрывает календарь. После закрытия фокус возвращается на
+поле. В поле можно перейти Tab и набрать дату.
 
 ### SelectSingle
 
@@ -239,7 +301,8 @@ Enter или пробел выбирают день под фокусом и с
 пунктам и страницу не прокручивают. Отсчёт идёт от выбранного пункта: вниз —
 следующий за ним, вверх — предыдущий; без выбранного вниз — первый пункт,
 вверх — последний; с краёв — по кругу. Enter или пробел выбирают пункт под
-фокусом так же, как клик, Escape закрывает список. После закрытия фокус
+фокусом так же, как клик, Escape закрывает список. Tab и Shift+Tab ходят по
+пунктам по кругу и наружу не выводят, пока список открыт. После закрытия фокус
 возвращается на кнопку фильтра. У закрытого списка стрелки прокручивают
 страницу.
 
@@ -258,6 +321,85 @@ Enter или пробел выбирают день под фокусом и с
 внутри списка — нет. Открытие другого списка, календаря или меню
 закрывает предыдущее.
 
+### SelectMultiple
+
+    <select-multiple
+        header="Бренд"
+        :items="[{ id: 'rc', name: 'Royal Canin' }, { id: 'eukanuba', name: 'Eukanuba' }]"
+        v-model="brands"
+        @changed="reload"
+    />
+
+    <select-multiple header="Мероприятие" :items="events" v-model="eventIds" with-search @changed="reload"/>
+
+Тот же фильтр, что `SelectSingle`, но выбрать можно несколько пунктов.
+`items` — массив объектов `{ id, name }`. `v-model` держит массив `id`
+выбранных пунктов, пустой массив — ничего не выбрано. `id` — строка или число,
+сравнение строгое.
+
+| Проп | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `items` | `Array` | обязателен | Массив `{ id, name }` |
+| `modelValue` | `Array` | `[]` | `id` выбранных пунктов |
+| `header` | `String` | обязателен | Подпись поля |
+| `isRequired` | `Boolean` | `false` | Пометка обязательности в заголовке |
+| `isLoading` | `Boolean` | `false` | Индикатор загрузки в заголовке |
+| `withSearch` | `Boolean` | `false` | Поле поиска вверху списка |
+| `lang` | `String` | язык плагина | `"ru"` или `"en"` — надпись, поле поиска, «Ничего не найдено», подписи обоих ластиков |
+
+События: `update:modelValue` — новый массив `id`; `changed` — после каждого
+изменения выбора кликом по пункту или ластиком.
+
+Клик по невыбранному пункту добавляет его `id` в конец массива, по выбранному —
+убирает. Массив из пропа компонент не меняет: он отдаёт новый, порядок `id` не
+сортирует. `id`, которых нет среди пунктов, при переключении других пунктов
+остаются в массиве, в надписи не считаются и ластик сами не показывают;
+ластик отдаёт `[]` — уходят и они. `null` и `undefined` в `items` — пустой
+список, в `modelValue` — ничего не выбрано.
+
+На кнопке: пока выбранных среди `items` нет — пусто; один — его название;
+несколько — «Выбрано: 3». Считаются все пункты, а не только найденные поиском.
+Ластик виден, когда выбран хотя бы один пункт и список закрыт.
+
+Выбор пункта — клик, Enter или пробел — закрывает список, фокус возвращается
+на кнопку фильтра, а запрос поиска сбрасывается. `changed` уходит после
+каждого выбора, и страница сразу перезапрашивает выдачу.
+
+Список открывается так же, как у `SelectSingle`: в верхнем слое браузера, место,
+высота, прокрутка и способы закрытия те же, фокус после закрытия возвращается
+на кнопку. Отличия: галочка стоит у каждого выбранного пункта; пункт
+сообщает скринридеру, выбран ли он (`aria-pressed`).
+Как и у `SelectSingle`, без пунктов кнопки нет, заголовок остаётся. Пункты
+пропали при открытом списке — список закрывается, запрос поиска сбрасывается,
+а вернувшиеся пункты появляются с закрытым списком.
+
+С клавиатуры, пока список открыт, всё как у `SelectSingle`: стрелки вверх и вниз
+ведут фокус по пунктам по кругу, Enter или пробел переключают пункт и закрывают
+список, Escape закрывает его без выбора. Если выбрано несколько пунктов,
+отсчёт идёт от первого выбранного среди видимых. Мышь ведёт тот же фокус, что
+и стрелки: движение по пункту ставит фокус на него, подсвечен всегда один пункт.
+
+С `with-search` над пунктами стоит поле поиска: при прокрутке длинного списка
+оно остаётся на месте. Имя пункта должно содержать запрос, регистр не важен,
+пробелы по краям запроса отбрасываются. Если совпадений нет, вместо пунктов
+строка «Ничего не найдено». Выбранные пункты, скрытые поиском, остаются
+выбранными. Запрос не входит в `v-model`; он сбрасывается при каждом закрытии
+списка, в том числе при выборе пункта. Ластик в поле очищает запрос. При
+открытии списка фокус встаёт в поле; при загрузке страницы фокус в поле
+не уходит. Без Popover API список виден всегда, и фокус в поле сам
+не ставится. Пробел в поле печатает пробел, Enter ничего не делает и форму
+не отправляет. Поле — первая остановка стрелок: из него вниз — первый пункт,
+вверх — последний, с краёв пунктов — обратно в поле. Без совпадений стрелки
+в поле ничего не делают. Пока список открыт, Tab и Shift+Tab ходят по кругу
+внутри него: поле, ластик поля, пока запрос не пуст, пункты; наружу, на
+страницу, фокус уходит после закрытия списка. Ластик поля входит в Tab, но не
+в стрелки. Ластик на кнопке фильтра идёт в Tab сразу после неё.
+Печатный символ и Backspace на пункте уходят в поле, поэтому набор не
+пропадает, когда мышь увела фокус на пункт. Пока список открыт, панель не
+становится уже, чем при открытии, а поле не двигается, сколько бы пунктов ни
+убрал поиск: открытая вниз панель становится ниже вместе с найденным, открытая
+вверх не становится ниже, и пустое место остаётся под пунктами, у кнопки.
+
 ### InfoPill
 
 Пилюля, которая только показывает текст: статус, счётчик, флаг, пометку.
@@ -866,7 +1008,10 @@ rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: фор
 | `HamburgerMenu` — подпись кнопки для скринридера | Открыть меню | Open menu |
 | `SelectDateInterval` — месяцы, дни недели, кнопки календарей | по-русски | in English |
 | `SelectDateInterval` — подсказки полей | от / до | from / to |
-| Ластик `Search`, `RussianMobileFilter`, `SelectSingle` (язык плагина) и `SelectDateInterval` — подпись для скринридера | Очистить | Clear |
+| Ластик `Search`, `RussianMobileFilter`, `SelectSingle` (язык плагина), `SelectMultiple` (проп `lang`) и `SelectDateInterval` — подпись для скринридера | Очистить | Clear |
+| `SelectMultiple` — надпись при нескольких выбранных | Выбрано: N | Selected: N |
+| `SelectMultiple` — подсказка и имя поля поиска | Поиск | Search |
+| `SelectMultiple` — нет совпадений | Ничего не найдено | Nothing found |
 | `DataTable` — пагинация | Предыдущая / Следующая / Показаны результаты X - Y из Z | Previous / Next / Showing X - Y of Z results |
 | `PageTabs` — имя навигации для скринридера | Закладки | Tabs |
 | `PageCard` — доступное имя крестика | Назад | Back |
@@ -881,7 +1026,20 @@ rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: фор
 
 Кнопки и ссылки компонентов нажимаются расширениями клавиатурной навигации —
 Vimium, Vimari, Vimlike — по их подсказкам, как мышью; подсказка у каждой
-кнопки одна и стоит на всей кнопке.
+кнопки одна и стоит на всей кнопке. Ластики фильтров входят в порядок Tab
+и нажимаются Enter и пробелом; кольцо фокуса — вокруг крестика.
+После ластика, нажатого с клавиатуры, фокус переходит на поле или кнопку
+этого фильтра: ластик пропадает, и без этого фокус упал бы на страницу.
+При касании и клике мышью фокус остаётся как раньше.
+
+Фокус у всех компонентов пакета выглядит одинаково, как у `FormInput`: линия
+1px `blue-300` по краю элемента и ореол 3px `blue-200` с прозрачностью 50%.
+Вид задан одной утилитой `focus-ring` в `src/styles/index.css`, компоненты
+выбирают только момент. Поля, крестик `NotificationMessage`, кнопки
+`ConfirmationModal` и `DropdownButtonWithAction` показывают фокус при любом
+его появлении, в том числе после клика мышью; остальные кнопки и ссылки —
+только с клавиатуры. Стрелки месяцев и подпись месяца в календаре `PickDay`
+берут тот же вид, когда фокус в них с клавиатуры.
 
 Vimlike (Safari на iPhone, iPad и Mac) считает кнопкой любой элемент
 с `cursor: pointer` и из вложенных таких элементов оставляет самый глубокий.
@@ -895,7 +1053,7 @@ Vimlike (Safari на iPhone, iPad и Mac) считает кнопкой любо
 считал бы кнопкой вместо неё. В поле по-прежнему можно перейти Tab и набрать
 дату.
 
-Подсказки Vimlike в открытых меню, списке `SelectSingle` и календарях
+Подсказки Vimlike в открытых меню, списках `SelectSingle` и `SelectMultiple` и календарях
 `SelectDateInterval` не видны: Vimlike рисует их под верхним слоем браузера,
 в котором открываются эти панели. Vimium выводит свои подсказки в верхний
 слой, и у него такой проблемы нет. В Vimlike панель открывают подсказкой её
@@ -1006,7 +1164,7 @@ Inertia SSR), а серверная разметка гидратируется
 
     npm run playground
 
-Поднимает демо-страницы со всеми семнадцатью компонентами в двух окружениях:
+Поднимает демо-страницы со всеми девятнадцатью компонентами в двух окружениях:
 голом (без Tailwind и стилей приложения) и в окружении приложения (с
 Tailwind, `@tailwindcss/forms` и типографикой, как у потребителя). Это
 основной способ посмотреть, как компоненты выглядят и ведут себя, а не