@boobooking/dashboard-ui-components 0.19.1 → 0.21.0

package/README.md

@@ -7,7 +7,7 @@
     npm install @boobooking/dashboard-ui-components
 
 ```js
-import { RussianMobileFilter, SelectDateInterval } from '@boobooking/dashboard-ui-components'
+import { RussianMobileFilter, SelectDateIntervalFilter } from '@boobooking/dashboard-ui-components'
 import '@boobooking/dashboard-ui-components/style.css'
 ```
 
@@ -65,10 +65,12 @@ Vue не ниже 3.5, ESM, сборщик, умеющий импорт CSS из
 Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в CSS приложения
 пакету не нужны.
 
-Меню `DropdownButtonWithAction` и `HamburgerMenu`, списки `SelectSingle` и `SelectMultiple`,
-календари `SelectDateInterval` и подсказка `TextPopover` стоят на Popover API
-браузера: Safari 17+, Chrome 114+, Firefox 125+. В браузерах старше меню,
-списки, календари и подсказка видны в потоке всегда.
+Меню `DropdownButtonWithAction` и `HamburgerMenu`, списки `SelectSingleFilter`,
+`SelectSingleForm`, `SelectMultipleFilter` и `SelectMultipleForm`, календари
+`SelectDateFilter`, `SelectDateForm`, `SelectDateIntervalFilter`,
+`SelectDateIntervalForm` и подсказка `TextPopover`
+стоят на Popover API браузера: Safari 17+, Chrome 114+, Firefox 125+. В браузерах
+старше меню, списки, календари и подсказка видны в потоке всегда.
 
 ## Цвета
 
@@ -82,7 +84,7 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 | --- | --- |
 | `InfoPill`, `ActionPill` | фон `-100`, текст `-800`; у `ActionPill` при наведении текст `-600` |
 | основная кнопка и стрелка `DropdownButtonWithAction` | фон `-100`, рамка `-300`, текст `-800`, при наведении фон `-200` |
-| пункт меню `DropdownButtonWithAction` и `HamburgerMenu` | текст `-800`, в фокусе фон `-100` |
+| пункт меню `DropdownButtonWithAction` и `HamburgerMenu` | фон `-100`, текст `-800`, при наведении и в фокусе фон `-200` |
 | `Dot`, полоска строки `DataTable` | `-500` |
 
 Без цвета кнопка белая с серой рамкой, пункт меню серый, строка таблицы без
@@ -90,10 +92,13 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 
 ## Компоненты
 
-Пакет экспортирует девятнадцать компонентов: `Dot`, `RussianMobileFilter`,
-`Search`, `SelectDateInterval`, `SelectSingle`, `SelectMultiple`, `InfoPill`,
-`ErrorMessages`, `FormInput`, `ActionPill`, `ConfirmationModal`,
-`DropdownButtonWithAction`, `HamburgerMenu`, `DataTable`,
+Пакет экспортирует двадцать шесть компонентов: `Dot`, `RussianMobileFilter`,
+`Search`, `SelectDateFilter`, `SelectDateForm`, `SelectDateIntervalFilter`,
+`SelectDateIntervalForm`,
+`SelectSingleFilter`, `SelectSingleForm`, `SelectMultipleFilter`,
+`SelectMultipleForm`, `SelectSingleCards`, `SelectMultipleList`, `InfoPill`,
+`ErrorMessages`, `FormInput`, `ActionPill`,
+`ConfirmationModal`, `DropdownButtonWithAction`, `HamburgerMenu`, `DataTable`,
 `NavigationMenuElement`, `PageTabs`, `PageCard`, `NotificationMessage`,
 `TextPopover`, функцию `downloadFile` и плагин `dashboardUi`. В архив пакета
 (`files: ["dist"]`) исходники не попадают, поэтому контракт каждого
@@ -225,14 +230,77 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 `isRequired` только показывает точку: атрибут `required` и `aria-*` полю
 он не ставит.
 
-### SelectDateInterval
+### SelectDateFilter
+
+Одно поле даты под заголовком. Дата выбирается в календаре Pikaday,
+у поля — ластик очистки. Подсказки у поля нет. Pikaday загружается
+в браузере при монтировании компонента, а не при загрузке пакета, поэтому
+календарь появляется, когда загрузка закончится.
+
+Высота 4.5rem и серая рамка встроены в фильтр, ширина поля 9rem: класс
+`h-18 border border-gray-200` ему не нужен. `class` и остальные атрибуты
+ложатся на корень фильтра.
+
+    <select-date-filter header="Дата" v-model="day" @changed="reload"/>
+
+| Проп | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `modelValue` | `String` | `""` | Выбранная дата |
+| `header` | `String` | обязателен | Подпись поля |
+| `isRequired` | `Boolean` | `false` | Пометка обязательности в заголовке |
+| `isLoading` | `Boolean` | `false` | Индикатор загрузки в заголовке |
+| `lang` | `String` | язык плагина | `"ru"` или `"en"`; действует на календарь и на подпись ластика для скринридера (у самого поля текста нет) |
+
+События: `update:modelValue` (дата или пустая строка после ластика)
+и `changed` приходят на каждый выбор пользователя: в том числе на повторный
+выбор уже показанной даты, на набранную в поле дату, которая разобралась,
+и на очистку ластиком. Когда значение меняет родитель, ни одно из событий
+не приходит. Поля диапазона `SelectDateIntervalFilter` и
+`SelectDateIntervalForm` устроены иначе: их `changed` приходит, только когда
+новое значение отличается от переданного пропса.
+
+Календарь, ластик и клавиатура — как у каждого из двух полей
+`SelectDateIntervalFilter` (см. «SelectDateIntervalFilter»).
+
+### SelectDateForm
+
+Одно поле даты в форме, в виде `FormInput`: подпись над полем, рамка поля
+на всю ширину формы, высотой 38px, как у `FormInput`. Рамка скругляет и поле,
+и кольцо фокуса в нём. Подсказки у поля нет.
+
+    <select-date-form label="Дата" v-model="day" :is-required="markDayRequired"/>
+
+| Проп | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `modelValue` | `String` | `""` | Выбранная дата |
+| `label` | `String` | обязателен | Подпись над полем |
+| `isRequired` | `Boolean` | `false` | Красная точка у подписи |
+| `lang` | `String` | язык плагина | `"ru"` или `"en"`; действует на календарь и на подпись ластика для скринридера (у самого поля текста нет) |
+
+События: `update:modelValue` и `changed` — когда значение выбрал пользователь,
+как у `SelectDateFilter` (см. «SelectDateFilter»); смена значения родителем
+их не вызывает. Календарь, ластик и клавиатура — тоже как у него.
+
+Подпись связана с полем для скринридера: кнопка календаря называется
+подписью и датой, поле ввода — подписью. Клик по подписи ничего не делает.
+
+`isRequired` только показывает точку, как у `FormInput`. `class`, `style`,
+все остальные атрибуты и слушатели ложатся на корень компонента (у `FormInput`
+остальные атрибуты уходят на поле ввода).
+
+### SelectDateIntervalFilter
 
 Два поля даты под одним заголовком — интервал дат «от» и «до». Дата
 выбирается в календаре Pikaday, у каждого поля — ластик очистки. Pikaday
 загружается в браузере при монтировании компонента, а не при загрузке
 пакета, поэтому календари появляются, когда загрузка закончится.
 
-    <select-date-interval
+Высота 4.5rem и серая рамка встроены в фильтр: класс
+`h-18 border border-gray-200` ему не нужен. Ширина фильтра 18rem, «от» и «до»
+по половине, между ними вертикальная линия. `class` и остальные атрибуты
+ложатся на корень фильтра.
+
+    <select-date-interval-filter
         header="Период"
         :date-from="dateFrom"
         :date-to="dateTo"
@@ -253,7 +321,8 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 События: `update:dateFrom`, `update:dateTo` — на каждый выбор даты
 в соответствующем поле и на его очистку ластиком (пустой строкой);
 `changed` — когда новое значение отличается от переданного пропса
-(отдельно для каждой из двух дат).
+(отдельно для каждой из двух дат). Повторный выбор уже показанной даты
+событий не вызывает.
 
 Клик по любому месту поля открывает его календарь. Календарь открывается
 в верхнем слое браузера (Popover API): его не обрезает обёртка
@@ -274,9 +343,42 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 же, как клик; Escape закрывает календарь. После закрытия фокус возвращается на
 поле. В поле можно перейти Tab и набрать дату.
 
-### SelectSingle
+### SelectDateIntervalForm
+
+Интервал дат в форме, в виде `FormInput`: подпись над полями, под ней «от»
+и «до» одинаковой ширины на всю ширину формы. У каждого поля своя рамка, как
+у `FormInput`, высотой 38px; рамка скругляет и поле, и кольцо фокуса в нём.
 
-    <select-single
+    <select-date-interval-form
+        label="Период"
+        v-model:date-from="dateFrom"
+        v-model:date-to="dateTo"
+        :is-required="markPeriodRequired"
+    />
+
+| Проп | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `dateFrom` | `String` | `""` | Начало интервала |
+| `dateTo` | `String` | `""` | Конец интервала |
+| `label` | `String` | обязателен | Подпись над полями |
+| `isRequired` | `Boolean` | `false` | Красная точка у подписи |
+| `lang` | `String` | язык плагина | `"ru"` или `"en"`; действует и на подсказки полей, и на оба календаря |
+
+События те же, что у `SelectDateIntervalFilter`: `update:dateFrom`,
+`update:dateTo` и `changed`. Календари, ластики, подсказки и клавиатура —
+тоже как у него (см. «SelectDateIntervalFilter»).
+
+Подпись связана с полями для скринридера: оба поля — группа, названная
+подписью, а каждое поле, как в фильтре, называется своей подсказкой «от» или
+«до» с датой. Клик по подписи ничего не делает.
+
+`isRequired` только показывает точку, как у `FormInput`. `class`, `style`,
+все остальные атрибуты и слушатели ложатся на корень компонента (у `FormInput`
+остальные атрибуты уходят на поле ввода).
+
+### SelectSingleFilter
+
+    <select-single-filter
         header="Вендор"
         :items="[{ id: 'a', name: 'Первый' }]"
         v-model="vendor"
@@ -298,6 +400,11 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 События: `update:modelValue` и `changed` — при выборе элемента (повторный
 клик по уже выбранному снимает выбор) и при очистке через ластик.
 
+Высота 4.5rem и серая рамка встроены в фильтр: класс
+`h-18 border border-gray-200` ему не нужен. `class` и остальные атрибуты
+ложатся на корень фильтра. Без пунктов кнопки нет, а заголовок, высота и рамка
+остаются.
+
 С клавиатуры: пока список открыт, стрелки вверх и вниз переводят фокус по
 пунктам и страницу не прокручивают. Отсчёт идёт от выбранного пункта: вниз —
 следующий за ним, вверх — предыдущий; без выбранного вниз — первый пункт,
@@ -307,9 +414,9 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 возвращается на кнопку фильтра. У закрытого списка стрелки прокручивают
 страницу.
 
-Подсветка пункта — это фокус, и мышь ведёт тот же фокус: движение по пункту
-ставит фокус на него, стрелки продолжают от пункта под курсором. Подсвечен
-всегда один пункт — тот, на который последними указали клавиатура или мышь.
+Наведение подсвечивает пункт, но фокус не двигает: фокус меняют клавиатура и
+клик. Пункт под мышью и пункт в фокусе с клавиатуры могут быть подсвечены
+одновременно; стрелки продолжают от пункта в фокусе.
 
 Список открывается в верхнем слое браузера (Popover API): его не обрезает
 обёртка с прокруткой. Он открывается под полем, левым краем по левому
@@ -322,18 +429,50 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 внутри списка — нет. Открытие другого списка, календаря или меню
 закрывает предыдущее.
 
-### SelectMultiple
+### SelectSingleForm
 
-    <select-multiple
+Выбор одного пункта в форме, в виде `FormInput`: подпись над полем, рамка
+поля на всю ширину формы, высотой 38px, как у `FormInput`. В рамке — кнопка
+со списком и ластиком, та же, что у `SelectSingleFilter`.
+
+    <select-single-form
+        label="Вендор"
+        :items="vendors"
+        v-model="vendor"
+        :is-required="markVendorRequired"
+    />
+
+| Проп | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `items` | `Array` | обязателен | Массив `{ id, name }` |
+| `modelValue` | `String \| Number` | `null` | `id` выбранного элемента или `null` |
+| `label` | `String` | обязателен | Подпись над полем |
+| `isRequired` | `Boolean` | `false` | Красная точка у подписи |
+
+`items`, `v-model`, события, список и клавиатура — как у `SelectSingleFilter`
+(см. «SelectSingleFilter»). Без пунктов кнопки нет, под подписью остаётся
+пустая рамка.
+
+Подпись связана с кнопкой для скринридера: кнопка называется подписью
+и выбранным пунктом, у пустого поля — подписью. Клик по подписи ничего
+не делает.
+
+`isRequired` только показывает точку, как у `FormInput`. `class`, `style`,
+все остальные атрибуты и слушатели ложатся на корень компонента (у `FormInput`
+остальные атрибуты уходят на поле ввода).
+
+### SelectMultipleFilter
+
+    <select-multiple-filter
         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"/>
+    <select-multiple-filter header="Мероприятие" :items="events" v-model="eventIds" with-search @changed="reload"/>
 
-Тот же фильтр, что `SelectSingle`, но выбрать можно несколько пунктов.
+Тот же фильтр, что `SelectSingleFilter`, но выбрать можно несколько пунктов.
 `items` — массив объектов `{ id, name }`. `v-model` держит массив `id`
 выбранных пунктов, пустой массив — ничего не выбрано. `id` — строка или число,
 сравнение строгое.
@@ -367,19 +506,20 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 на кнопку фильтра, а запрос поиска сбрасывается. `changed` уходит после
 каждого выбора, и страница сразу перезапрашивает выдачу.
 
-Список открывается так же, как у `SelectSingle`: в верхнем слое браузера, место,
+Список открывается так же, как у `SelectSingleFilter`: в верхнем слое браузера, место,
 высота, прокрутка и способы закрытия те же, фокус после закрытия возвращается
 на кнопку. Отличия: галочка стоит у каждого выбранного пункта; пункт
 сообщает скринридеру, выбран ли он (`aria-pressed`).
-Как и у `SelectSingle`, без пунктов кнопки нет, заголовок остаётся. Пункты
-пропали при открытом списке — список закрывается, запрос поиска сбрасывается,
-а вернувшиеся пункты появляются с закрытым списком.
+Как и у `SelectSingleFilter`, без пунктов кнопки нет, а заголовок, высота
+и рамка остаются. Пункты пропали при открытом списке — список закрывается,
+запрос поиска сбрасывается, а вернувшиеся пункты появляются с закрытым списком.
 
-С клавиатуры, пока список открыт, всё как у `SelectSingle`: стрелки вверх и вниз
-ведут фокус по пунктам по кругу, Enter или пробел переключают пункт и закрывают
-список, Escape закрывает его без выбора. Если выбрано несколько пунктов,
-отсчёт идёт от первого выбранного среди видимых. Мышь ведёт тот же фокус, что
-и стрелки: движение по пункту ставит фокус на него, подсвечен всегда один пункт.
+С клавиатуры, пока список открыт, всё как у `SelectSingleFilter`: стрелки вверх
+и вниз ведут фокус по пунктам по кругу, Enter или пробел переключают пункт и
+закрывают список, Escape закрывает его без выбора. Если выбрано несколько
+пунктов, отсчёт идёт от первого выбранного среди видимых. Наведение подсвечивает
+пункт, но фокус не двигает: фокус меняют клавиатура и клик, пункт под мышью и
+пункт в фокусе могут быть подсвечены одновременно.
 
 С `with-search` над пунктами стоит поле поиска: при прокрутке длинного списка
 оно остаётся на месте. Имя пункта должно содержать запрос, регистр не важен,
@@ -387,21 +527,172 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 строка «Ничего не найдено». Выбранные пункты, скрытые поиском, остаются
 выбранными. Запрос не входит в `v-model`; он сбрасывается при каждом закрытии
 списка, в том числе при выборе пункта. Ластик в поле очищает запрос. При
-открытии списка фокус встаёт в поле; при загрузке страницы фокус в поле
-не уходит. Без Popover API список виден всегда, и фокус в поле сам
-не ставится. Пробел в поле печатает пробел, Enter ничего не делает и форму
-не отправляет. Поле — первая остановка стрелок: из него вниз — первый пункт,
-вверх — последний, с краёв пунктов — обратно в поле. Без совпадений стрелки
-в поле ничего не делают. Пока список открыт, Tab и Shift+Tab ходят по кругу
-внутри него: поле, ластик поля, пока запрос не пуст, пункты; наружу, на
-страницу, фокус уходит после закрытия списка. Ластик поля входит в Tab, но не
-в стрелки. Ластик на кнопке фильтра идёт в Tab сразу после неё.
-Печатный символ и Backspace на пункте уходят в поле, поэтому набор не
-пропадает, когда мышь увела фокус на пункт. Пока список открыт, панель не
+открытии списка фокус встаёт в поле; при загрузке страницы фокус в поле не
+уходит. Без Popover API список виден всегда, и фокус в поле сам не ставится.
+Пробел в поле печатает пробел, Enter ничего не делает и форму не отправляет.
+Поле — первая остановка стрелок: из него вниз — первый пункт, вверх — последний,
+с краёв пунктов — обратно в поле. Без совпадений стрелки в поле ничего не
+делают. Пока список открыт, Tab и Shift+Tab ходят по кругу внутри него: поле,
+ластик поля, пока запрос не пуст, пункты; наружу, на страницу, фокус уходит
+после закрытия списка. Ластик поля входит в Tab, но не в стрелки. Ластик на
+кнопке фильтра идёт в Tab сразу после неё. Печатный символ и Backspace на
+пункте, куда фокус перевели стрелки или Tab, уходят в поле, поэтому набор не
+пропадает; мышь фокус на пункт не уводит. Пока список открыт, панель не
 становится уже, чем при открытии, а поле не двигается, сколько бы пунктов ни
 убрал поиск: открытая вниз панель становится ниже вместе с найденным, открытая
 вверх не становится ниже, и пустое место остаётся под пунктами, у кнопки.
 
+### SelectMultipleForm
+
+Выбор нескольких пунктов в форме, в виде `FormInput`: подпись над полем, рамка
+поля на всю ширину формы, высотой 38px, как у `FormInput`. В рамке — кнопка
+со списком, поиском и ластиком, та же, что у `SelectMultipleFilter`.
+
+    <select-multiple-form label="Бренд" :items="brands" v-model="brandIds"/>
+
+    <select-multiple-form label="Мероприятие" :items="events" v-model="eventIds" with-search :is-required="markEventsRequired"/>
+
+| Проп | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `items` | `Array` | обязателен | Массив `{ id, name }` |
+| `modelValue` | `Array` | `[]` | `id` выбранных пунктов |
+| `label` | `String` | обязателен | Подпись над полем |
+| `isRequired` | `Boolean` | `false` | Красная точка у подписи |
+| `withSearch` | `Boolean` | `false` | Поле поиска вверху списка |
+| `lang` | `String` | язык плагина | `"ru"` или `"en"` — надпись, поле поиска, «Ничего не найдено», подписи обоих ластиков |
+
+`items`, `v-model`, события, надпись на кнопке, список, поиск и клавиатура —
+как у `SelectMultipleFilter` (см. «SelectMultipleFilter»). Без пунктов кнопки
+нет, под подписью остаётся пустая рамка.
+
+Подпись связана с кнопкой для скринридера: кнопка называется подписью
+и надписью на кнопке, у пустого поля — подписью. Клик по подписи ничего
+не делает.
+
+`isRequired` только показывает точку, как у `FormInput`. `class`, `style`,
+все остальные атрибуты и слушатели ложатся на корень компонента (у `FormInput`
+остальные атрибуты уходят на поле ввода).
+
+### SelectSingleCards
+
+Выбор одного пункта карточками в форме: подпись над карточками, в каждой
+карточке кружок слева и надпись. У выбранной карточки синяя рамка, светло-синий
+фон и точка в кружке. Карточки стоят в несколько колонок на всю ширину формы.
+
+    <select-single-cards label="Бренд" :items="brands" v-model="brand" :is-required="markBrandRequired"/>
+
+| Проп | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `items` | `Array` | обязателен | Массив `{ id, name }` |
+| `modelValue` | `String \| Number \| Boolean` | `null` | `id` выбранного пункта или `null` |
+| `label` | `String` | обязателен | Подпись над карточками |
+| `isRequired` | `Boolean` | `false` | Красная точка у подписи |
+| `columns` | `Number` | `2` | Число колонок, целое от 1; иначе — две колонки. Vue предупреждает о нецелом, меньшем 1 и нечисловом значении, но не о `null` |
+
+Событий два: `update:modelValue` с `id` выбранного пункта и сразу за ним
+`changed`, после каждого выбора пользователя. `id` уходит в событие как есть,
+без приведения к строке: строки, числа и `true` / `false` сравниваются строго.
+Надпись карточки — `name`.
+
+Без пунктов (`items` пуст, `null` или не массив) видна только подпись, сетки нет;
+элементы, не являющиеся объектами, пропускаются.
+
+Клик в любом месте карточки выбирает её. Клик по уже выбранной карточке
+ничего не меняет и событий не вызывает: выбор не снимается, «ничего не
+выбрано» бывает только до первого выбора. Если `modelValue` не совпадает
+ни с одним `id`, не выбрана ни одна карточка.
+
+Если родитель не принял значение (не обновил `modelValue` в ответ на
+`update:modelValue`), выбранной остаётся карточка, которую задаёт проп.
+
+Колонки компонент раскладывает сам: пункты идут по колонкам в порядке массива,
+сначала заполняется первая колонка сверху вниз, потом вторая и так далее.
+Длины колонок различаются не больше чем на один пункт, лишние пункты достаются
+первым колонкам. Для `n` пунктов и `c` колонок:
+
+| `n` | `c` | Колонки |
+| --- | --- | --- |
+| 14 | 2 | 7, 7 |
+| 14 | 3 | 5, 5, 4 |
+| 4 | 3 | 2, 1, 1 |
+| 2 | 2 | 1, 1 |
+| 2 | 3 | 1, 1, пустая |
+| 1 | 2 | 1, пустая |
+
+Колонки одинаковой ширины, их число всегда равно `columns`: при `n < c`
+пустые колонки остаются местом справа, и ширина карточек от числа пунктов не
+зависит. Карточки одной строки одной высоты, по самой высокой: так надпись,
+перенесённая на две строки, не делает соседнюю карточку ниже. Колонки не
+перестраиваются под узкий экран. Порядок Tab и стрелок — порядок массива, а не
+порядок строк на экране.
+
+С клавиатуры карточки ведут себя как родная группа переключателей: Tab входит
+в группу один раз — на выбранную карточку, а если выбранной нет, на первую;
+следующий Tab уходит из группы. Стрелки переходят к соседней карточке в
+порядке массива и выбирают её, пробел выбирает карточку под фокусом. Кольцо
+фокуса — вокруг всей карточки, только при фокусе с клавиатуры.
+
+Для скринридера сетка карточек — группа `radiogroup`, названная подписью;
+каждая карточка называется своей надписью. Клик по подписи ничего не делает.
+
+В режиме высокой контрастности (`forced-colors: active`) браузер заменяет цвета
+системными, а выбранная карточка остаётся видна: точка в кружке — системным
+цветом текста, кружок — цветом выделения. Кольцо фокуса в этом режиме — одна
+линия, ореол браузер снимает.
+
+`isRequired` только показывает точку, как у `FormInput`: атрибутов `required`
+и `aria-required` компонент не ставит. `class`, `style`, все остальные атрибуты
+и слушатели ложатся на корень компонента. Своих надписей у компонента нет,
+поэтому `lang` нет. Вид не зависит от preflight и `@tailwindcss/forms`
+приложения: кружок и точку рисует сам компонент.
+
+### SelectMultipleList
+
+Выбор нескольких пунктов списком галочек в форме: подпись над списком, у
+каждого пункта квадрат с галочкой и надпись. Отмеченный квадрат закрашен
+индиго с белой галочкой. Пункты стоят в несколько колонок.
+
+    <select-multiple-list label="Участники" :items="participantTypes" v-model="participants" :columns="2"/>
+
+| Проп | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `items` | `Array` | обязателен | Массив `{ id, name }` |
+| `modelValue` | `Array` | `[]` | `id` отмеченных пунктов |
+| `label` | `String` | обязателен | Подпись над списком |
+| `isRequired` | `Boolean` | `false` | Красная точка у подписи |
+| `columns` | `Number` | `2` | Число колонок, целое от 1; иначе — две колонки. Vue предупреждает о нецелом, меньшем 1 и нечисловом значении, но не о `null` |
+
+Событий два: `update:modelValue` с новым массивом и сразу за ним `changed`,
+после каждого выбора пользователя. Отметка добавляет `id` в конец массива,
+снятие убирает его; `id`, которых нет среди пунктов, остаются в значении.
+`modelValue`, не являющийся массивом, значит «ничего не отмечено». Клик по
+квадрату и по надписи отмечает или снимает пункт.
+
+Без пунктов (`items` пуст, `null` или не массив) видна только подпись, списка нет;
+элементы, не являющиеся объектами, пропускаются.
+
+Если родитель не принял значение (не обновил `modelValue`), отметки остаются
+такими, какими их задаёт проп.
+
+Раскладка по колонкам, ширина колонок, высота строк и порядок — как у
+`SelectSingleCards` (см. «SelectSingleCards»), в том числе таблица `n` / `c`.
+
+С клавиатуры каждая галочка — отдельная остановка Tab в порядке массива,
+пробел отмечает и снимает. Кольцо фокуса — вокруг квадрата, только при фокусе
+с клавиатуры.
+
+Для скринридера список — группа `group`, названная подписью; каждая галочка
+называется своей надписью. Клик по подписи ничего не делает.
+
+В режиме высокой контрастности (`forced-colors: active`) компонент показывает
+родные галочки браузера в системных цветах: свой закрашенный квадрат браузер
+перекрасил бы в цвет фона, и отмеченный пункт не отличался бы от неотмеченного.
+Кольцо фокуса в этом режиме — одна линия, как у `SelectSingleCards`.
+
+`isRequired`, `class`, `style`, остальные атрибуты и слушатели, отсутствие
+`lang` и независимость вида от preflight и `@tailwindcss/forms` — как у
+`SelectSingleCards`.
+
 ### InfoPill
 
 Пилюля, которая только показывает текст: статус, счётчик, флаг, пометку.
@@ -623,13 +914,16 @@ exportOrders() {
 таблицы и изменением размера окна. Открытие другого меню закрывает
 предыдущее.
 
-Пока меню открыто, стрелки вверх и вниз переводят фокус по пунктам и
-страницу не прокручивают: вниз — на первый пункт, вверх — на последний,
-дальше — по соседним, с краёв — по кругу. Enter на пункте под фокусом
-выбирает его. Подсветка пункта — это фокус, и мышь ведёт тот же фокус:
-движение по пункту ставит фокус на него, стрелки продолжают от пункта под
-курсором. Подсвечен всегда один пункт — тот, на который последними указали
-клавиатура или мышь.
+Пока меню открыто, стрелки вверх и вниз переводят фокус по пунктам и страницу не
+прокручивают: вниз — на первый пункт, вверх — на последний, дальше — по
+соседним, с краёв — по кругу. Enter на пункте под фокусом выбирает его.
+Наведение подсвечивает пункт, но фокус не двигает: фокус меняют клавиатура и
+клик. Пункт под мышью и пункт в фокусе с клавиатуры могут быть подсвечены
+одновременно; стрелки продолжают от пункта в фокусе.
+
+После закрытия меню фокус возвращается на стрелку, если он был внутри меню и
+после закрытия потерян. Фокус, который перешёл на другой элемент (например, в
+модалку, открытую пунктом), сохраняется.
 
 ### HamburgerMenu
 
@@ -675,9 +969,15 @@ Escape, клик по пункту, прокрутка и изменение р
 с `<hamburger-menu>` — `class`, `style`, `data-*` — ложатся на обёртку
 кнопки.
 
-Клавиатура и мышь — как в меню `DropdownButtonWithAction`: пока меню
-открыто, стрелки вверх и вниз переводят фокус по пунктам, Enter выбирает
-пункт под фокусом; подсветка пункта — это фокус, и мышь ведёт тот же фокус.
+Клавиатура и мышь — как в меню `DropdownButtonWithAction`: пока меню открыто,
+стрелки вверх и вниз переводят фокус по пунктам, Enter выбирает пункт под
+фокусом; наведение подсвечивает пункт, но фокус не двигает: фокус меняют
+клавиатура и клик, а пункт под мышью и пункт в фокусе могут быть подсвечены
+одновременно.
+
+После закрытия меню фокус возвращается на кнопку меню, если он был внутри меню
+и после закрытия потерян. Фокус, который перешёл на другой элемент (например, в
+модалку, открытую пунктом), сохраняется.
 
 ### DataTable
 
@@ -1008,12 +1308,12 @@ rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: фор
 | `ConfirmationModal` — кнопка отмены | Отмена | Cancel |
 | `DropdownButtonWithAction` — подпись стрелки для скринридера | Открыть меню | Open menu |
 | `HamburgerMenu` — подпись кнопки для скринридера | Открыть меню | Open menu |
-| `SelectDateInterval` — месяцы, дни недели, кнопки календарей | по-русски | in English |
-| `SelectDateInterval` — подсказки полей | от / до | from / to |
-| Ластик `Search`, `RussianMobileFilter`, `SelectSingle` (язык плагина), `SelectMultiple` (проп `lang`) и `SelectDateInterval` — подпись для скринридера | Очистить | Clear |
-| `SelectMultiple` — надпись при нескольких выбранных | Выбрано: N | Selected: N |
-| `SelectMultiple` — подсказка и имя поля поиска | Поиск | Search |
-| `SelectMultiple` — нет совпадений | Ничего не найдено | Nothing found |
+| `SelectDateFilter`, `SelectDateForm`, `SelectDateIntervalFilter`, `SelectDateIntervalForm` — месяцы, дни недели, кнопки календарей | по-русски | in English |
+| `SelectDateIntervalFilter`, `SelectDateIntervalForm` — подсказки полей | от / до | from / to |
+| Ластик `Search`, `RussianMobileFilter`, `SelectSingleFilter` и `SelectSingleForm` (язык плагина), `SelectMultipleFilter` и `SelectMultipleForm` (проп `lang`), `SelectDateFilter`, `SelectDateForm`, `SelectDateIntervalFilter` и `SelectDateIntervalForm` — подпись для скринридера | Очистить | Clear |
+| `SelectMultipleFilter`, `SelectMultipleForm` — надпись при нескольких выбранных | Выбрано: N | Selected: N |
+| `SelectMultipleFilter`, `SelectMultipleForm` — подсказка и имя поля поиска | Поиск | Search |
+| `SelectMultipleFilter`, `SelectMultipleForm` — нет совпадений | Ничего не найдено | Nothing found |
 | `DataTable` — пагинация | Предыдущая / Следующая / Показаны результаты X - Y из Z | Previous / Next / Showing X - Y of Z results |
 | `PageTabs` — имя навигации для скринридера | Закладки | Tabs |
 | `PageCard` — доступное имя крестика | Назад | Back |
@@ -1021,8 +1321,9 @@ rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: фор
 | `TextPopover` — подпись кнопки и имя области | Показать текст / Полный текст | Show text / Full text |
 
 Формат даты — `дд.мм.гггг` в обоих языках: это формат значения, а не текст.
-Неделя начинается с понедельника. Календари `SelectDateInterval` берут язык
-при монтировании: смена языка после монтирования в них не отражается.
+Неделя начинается с понедельника. Календари `SelectDateFilter`, `SelectDateForm`,
+`SelectDateIntervalFilter` и `SelectDateIntervalForm` берут язык при монтировании: смена языка после
+монтирования в них не отражается.
 
 ## Клавиатурная навигация
 
@@ -1036,11 +1337,15 @@ Vimium, Vimari, Vimlike — по их подсказкам, как мышью;
 
 Фокус у всех компонентов пакета выглядит одинаково, как у `FormInput`: линия
 1px `blue-300` по краю элемента и ореол 3px `blue-200` с прозрачностью 50%.
-Вид задан одной утилитой `focus-ring` в `src/styles/index.css`, компоненты
-выбирают только момент. Поля, крестик `NotificationMessage`, кнопки
+В режиме высокой контрастности (`forced-colors: active`) ореола нет, а линия
+отстоит от края элемента на 2px: на рамке того же системного цвета она бы
+слилась с ней. Вид задан одной утилитой `focus-ring` в `src/styles/index.css`,
+компоненты выбирают только момент. Поля, кроме `SelectSingleCards` и
+`SelectMultipleList`, крестик `NotificationMessage`, кнопки
 `ConfirmationModal` и `DropdownButtonWithAction` показывают фокус при любом
-его появлении, в том числе после клика мышью; остальные кнопки и ссылки —
-только с клавиатуры. Стрелки месяцев и подпись месяца в календаре `PickDay`
+его появлении, в том числе после клика мышью. Карточки `SelectSingleCards`,
+галочки `SelectMultipleList`, остальные кнопки и ссылки показывают фокус
+только с клавиатуры. Стрелки месяцев и подпись месяца в календаре поля даты
 берут тот же вид, когда фокус в них с клавиатуры.
 
 Vimlike (Safari на iPhone, iPad и Mac) считает кнопкой любой элемент
@@ -1050,17 +1355,23 @@ Vimlike (Safari на iPhone, iPad и Mac) считает кнопкой любо
 бы тексту, иконке, у которой нет `click()`, и скрытой подписи, которую Vimlike
 считает невидимой. Поэтому содержимое кнопок и ссылок пакета — текст, иконки,
 скрытые подписи — с курсором `default` и не ловит указатель: мышь над ним
-видит руку самой кнопки. По той же причине поле даты `SelectDateInterval`
-лежит не внутри кнопки календаря, а под ней: поле внутри кнопки Vimlike
-считал бы кнопкой вместо неё. В поле по-прежнему можно перейти Tab и набрать
-дату.
-
-Подсказки Vimlike в открытых меню, списках `SelectSingle` и `SelectMultiple` и календарях
-`SelectDateInterval` не видны: Vimlike рисует их под верхним слоем браузера,
-в котором открываются эти панели. Vimium выводит свои подсказки в верхний
-слой, и у него такой проблемы нет. В Vimlike панель открывают подсказкой её
-кнопки, а дальше выбирают стрелками и Enter: пункт списка или меню, день
-календаря.
+видит руку самой кнопки. По той же причине поле даты `SelectDateFilter`, `SelectDateForm`,
+`SelectDateIntervalFilter` и `SelectDateIntervalForm` лежит не внутри кнопки календаря, а под ней: поле
+внутри кнопки Vimlike считал бы кнопкой вместо неё. В поле по-прежнему можно
+перейти Tab и набрать дату.
+
+У карточки `SelectSingleCards` одна подсказка расширения на всей карточке,
+у галочки `SelectMultipleList` — одна на пункт. Safari на Mac без настройки
+Tab по всем объектам пропускает переключатели и галочки, как и кнопки пакета.
+
+Подсказки Vimlike в открытых меню, списках `SelectSingleFilter`,
+`SelectSingleForm`, `SelectMultipleFilter` и `SelectMultipleForm` и календарях
+`SelectDateFilter`, `SelectDateForm`, `SelectDateIntervalFilter`
+и `SelectDateIntervalForm` не видны: Vimlike рисует
+их под верхним слоем браузера, в котором открываются эти панели. Vimium
+выводит свои подсказки в верхний слой, и у него такой проблемы нет. В Vimlike
+панель открывают подсказкой её кнопки, а дальше выбирают стрелками и Enter:
+пункт списка или меню, день календаря.
 
 ## SSR
 
@@ -1071,8 +1382,10 @@ Inertia SSR), а серверная разметка гидратируется
 - `PageCard` на сервере рисует крестик, только если задан `fallback-url`:
   адрес возврата известен только в браузере, и крестик, ведущий на него,
   появляется после монтирования;
-- `SelectDateInterval` загружает Pikaday в браузере при монтировании:
-  календари появляются, когда загрузка закончится;
+- `SelectDateFilter`, `SelectDateForm`, `SelectDateIntervalFilter`
+  и `SelectDateIntervalForm` загружают Pikaday в браузере при монтировании:
+  календари появляются, когда загрузка
+  закончится;
 - остальные компоненты рендерятся на сервере так же, как в браузере.
 
 ## Правила API пакета
@@ -1083,12 +1396,13 @@ Inertia SSR), а серверная разметка гидратируется
 - Значение компонента передаётся через `v-model` (проп `modelValue` и
   событие `update:modelValue`) и не обязательно: компонент обязан
   отрисовываться без переданного значения. `required: true` оставляют
-  только там, без чего компонент бессмыслен, — например, у `items` в
-  `SelectSingle` или у `header` во всех фильтрах.
+  только там, без чего компонент бессмыслен, — например, у `items`
+  в `SelectSingleFilter` и `SelectSingleForm`, у `header` во всех фильтрах
+  или у `label` полей формы.
 - Именованные модели (`v-model:date-from`, `v-model:date-to`, как у
-  `SelectDateInterval`) — исключение для компонентов с несколькими
-  значениями. У компонента с одним значением именованная модель не нужна:
-  для него это и есть обычный `v-model`.
+  `SelectDateIntervalFilter` и `SelectDateIntervalForm`) — исключение для
+  компонентов с несколькими значениями. У компонента с одним значением
+  именованная модель не нужна: для него это и есть обычный `v-model`.
 - Булев проп называется `is*`, если описывает состояние компонента
   (`isRequired`, `isLoading`), и `with*`, если описывает необязательную
   возможность (`withPulse` у `Dot`).
@@ -1144,10 +1458,10 @@ Inertia SSR), а серверная разметка гидратируется
 
 Правило пакета — значение через `v-model` — относится к состоянию, которое
 компонент меняет сам: меню `DropdownButtonWithAction` закрывается по клику
-вне, `SelectSingle` меняет выбор. `ConfirmationModal` свою видимость не меняет
-никогда. Обе кнопки и Escape только сообщают родителю решение пользователя,
-а закрыть модалку, оставить её открытой на время запроса или открыть
-следующую — решает родитель.
+вне, `SelectSingleFilter` меняет выбор. `ConfirmationModal` свою видимость
+не меняет никогда. Обе кнопки и Escape только сообщают родителю решение
+пользователя, а закрыть модалку, оставить её открытой на время запроса или
+открыть следующую — решает родитель.
 
 `v-model` обещал бы двустороннюю связь, которой нет, поэтому видимость
 передаётся пропом `isOpen`.
@@ -1166,12 +1480,24 @@ Inertia SSR), а серверная разметка гидратируется
 
     npm run playground
 
-Поднимает демо-страницы со всеми девятнадцатью компонентами в двух окружениях:
+Поднимает демо-страницы со всеми двадцатью шестью компонентами в двух окружениях:
 голом (без Tailwind и стилей приложения) и в окружении приложения (с
 Tailwind, `@tailwindcss/forms` и типографикой, как у потребителя). Это
 основной способ посмотреть, как компоненты выглядят и ведут себя, а не
 угадывать по исходникам или по этому README.
 
+### Браузерные тесты
+
+    npm run test:browser
+
+Собирает пакет и прогоняет Playground в Chromium и WebKit — движке Safari.
+Установленный Safari тесты не запускают. Запускать на macOS: WebKit на Linux
+фокусирует кнопки по клику иначе, чем Safari. Перед первым запуском:
+
+    npx playwright install chromium webkit
+
+Тесты только локальные, в GitHub Actions они не входят.
+
 ## Что пакет берёт у приложения
 
 Базовую типографику — семейство шрифта, размер, `line-height`. Он наследует её
@@ -1182,6 +1508,43 @@ Tailwind, `@tailwindcss/forms` и типографикой, как у потре
 Правила номера телефона в `RussianMobileFilter` — российские; язык текстов
 задаётся, см. «Языки».
 
+## Обновление с 0.19
+
+| Было | Стало |
+| --- | --- |
+| `<select-single class="h-18 border border-gray-200" header="…">` | `<select-single-filter header="…">` — высота и рамка встроены |
+| `<select-multiple class="h-18 border border-gray-200" header="…">` | `<select-multiple-filter header="…">` |
+| `<select-date-interval class="h-18 border border-gray-200" header="…">` | `<select-date-interval-filter header="…">` |
+| `"select-source": SelectSingle` (проект регистрирует компонент под своим именем тега) | `"select-source": SelectSingleFilter`; так же для `SelectMultiple` и `SelectDateInterval` |
+| `SelectSingle` в форме рядом с `FormInput` | `<select-single-form label="…">` |
+| `SelectMultiple` в форме | `<select-multiple-form label="…">` |
+| `SelectDateInterval` в форме | `<select-date-interval-form label="…">` |
+
+`import { SelectSingle }` больше не работает: имена `SelectSingle`,
+`SelectMultiple` и `SelectDateInterval` из пакета убраны. Остальные классы
+на фильтрах (`ml-2` и т. п.) переносятся как есть.
+
+В формах меняются и пропы: `header` становится `label`, `class="border
+border-gray-200"` убирается (на корне формы он обвёл бы подпись вместе с полем),
+а `isLoading` у форм нет.
+
+Наведение мыши в списках и меню больше не двигает фокус: оно только подсвечивает
+пункт, фокус меняют клавиатура и клик.
+
+Цветные пункты меню `DropdownButtonWithAction` и `HamburgerMenu` теперь всегда
+с фоном своего цвета: например, красный пункт «Удалить» / «Delete» в меню
+строки получает светло-красный фон.
+
+В Safari фокус после закрытия меню `DropdownButtonWithAction` и `HamburgerMenu`
+— Escape, если фокус был в меню, выбор пункта мышью или клавиатурой, закрытие
+модалки, открытой пунктом, — возвращается на кнопку меню, как в Chrome.
+
+`SelectDateFilter` и `SelectDateForm` — новые компоненты одной даты, у них
+нет предшественника: в таблице их нет.
+
+`0.20.0` не подтянется по `^0.19.x`: для версий `0.x` знак `^` пропускает
+только патчи. Обновление — `npm install @boobooking/dashboard-ui-components@^0.20.0`.
+
 ## Обновление с 0.15
 
 | Было | Стало |