@boobooking/dashboard-ui-components 0.19.0 → 0.20.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,12 @@ 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`, `InfoPill`, `ErrorMessages`, `FormInput`, `ActionPill`,
+`ConfirmationModal`, `DropdownButtonWithAction`, `HamburgerMenu`, `DataTable`,
 `NavigationMenuElement`, `PageTabs`, `PageCard`, `NotificationMessage`,
 `TextPopover`, функцию `downloadFile` и плагин `dashboardUi`. В архив пакета
 (`files: ["dist"]`) исходники не попадают, поэтому контракт каждого
@@ -225,14 +229,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 +320,8 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 События: `update:dateFrom`, `update:dateTo` — на каждый выбор даты
 в соответствующем поле и на его очистку ластиком (пустой строкой);
 `changed` — когда новое значение отличается от переданного пропса
-(отдельно для каждой из двух дат).
+(отдельно для каждой из двух дат). Повторный выбор уже показанной даты
+событий не вызывает.
 
 Клик по любому месту поля открывает его календарь. Календарь открывается
 в верхнем слое браузера (Popover API): его не обрезает обёртка
@@ -274,9 +342,42 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 же, как клик; Escape закрывает календарь. После закрытия фокус возвращается на
 поле. В поле можно перейти Tab и набрать дату.
 
-### SelectSingle
+### SelectDateIntervalForm
+
+Интервал дат в форме, в виде `FormInput`: подпись над полями, под ней «от»
+и «до» одинаковой ширины на всю ширину формы. У каждого поля своя рамка, как
+у `FormInput`, высотой 38px; рамка скругляет и поле, и кольцо фокуса в нём.
+
+    <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»).
+
+Подпись связана с полями для скринридера: оба поля — группа, названная
+подписью, а каждое поле, как в фильтре, называется своей подсказкой «от» или
+«до» с датой. Клик по подписи ничего не делает.
 
-    <select-single
+`isRequired` только показывает точку, как у `FormInput`. `class`, `style`,
+все остальные атрибуты и слушатели ложатся на корень компонента (у `FormInput`
+остальные атрибуты уходят на поле ввода).
+
+### SelectSingleFilter
+
+    <select-single-filter
         header="Вендор"
         :items="[{ id: 'a', name: 'Первый' }]"
         v-model="vendor"
@@ -284,7 +385,8 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
     />
 
 `items` — массив объектов `{ id, name }`. `v-model` держит `id` выбранного или
-`null`, если не выбрано.
+`null`, если не выбрано. Не массив, в том числе `null` и `undefined`, — пустой
+список; элементы-необъекты в массиве пропускаются.
 
 | Проп | Тип | По умолчанию | Описание |
 | --- | --- | --- | --- |
@@ -297,6 +399,11 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 События: `update:modelValue` и `changed` — при выборе элемента (повторный
 клик по уже выбранному снимает выбор) и при очистке через ластик.
 
+Высота 4.5rem и серая рамка встроены в фильтр: класс
+`h-18 border border-gray-200` ему не нужен. `class` и остальные атрибуты
+ложатся на корень фильтра. Без пунктов кнопки нет, а заголовок, высота и рамка
+остаются.
+
 С клавиатуры: пока список открыт, стрелки вверх и вниз переводят фокус по
 пунктам и страницу не прокручивают. Отсчёт идёт от выбранного пункта: вниз —
 следующий за ним, вверх — предыдущий; без выбранного вниз — первый пункт,
@@ -306,9 +413,9 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 возвращается на кнопку фильтра. У закрытого списка стрелки прокручивают
 страницу.
 
-Подсветка пункта — это фокус, и мышь ведёт тот же фокус: движение по пункту
-ставит фокус на него, стрелки продолжают от пункта под курсором. Подсвечен
-всегда один пункт — тот, на который последними указали клавиатура или мышь.
+Наведение подсвечивает пункт, но фокус не двигает: фокус меняют клавиатура и
+клик. Пункт под мышью и пункт в фокусе с клавиатуры могут быть подсвечены
+одновременно; стрелки продолжают от пункта в фокусе.
 
 Список открывается в верхнем слое браузера (Popover API): его не обрезает
 обёртка с прокруткой. Он открывается под полем, левым краем по левому
@@ -321,18 +428,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` — строка или число,
 сравнение строгое.
@@ -354,8 +493,9 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 убирает. Массив из пропа компонент не меняет: он отдаёт новый, порядок `id` не
 сортирует. `id`, которых нет среди пунктов, при переключении других пунктов
 остаются в массиве, в надписи не считаются и ластик сами не показывают;
-ластик отдаёт `[]` — уходят и они. `null` и `undefined` в `items` — пустой
-список, в `modelValue` — ничего не выбрано.
+ластик отдаёт `[]` — уходят и они. Не массив в `items`, в том числе `null`
+и `undefined`, — пустой список, элементы-необъекты в нём пропускаются; `null`
+и `undefined` в `modelValue` — ничего не выбрано.
 
 На кнопке: пока выбранных среди `items` нет — пусто; один — его название;
 несколько — «Выбрано: 3». Считаются все пункты, а не только найденные поиском.
@@ -365,19 +505,20 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 на кнопку фильтра, а запрос поиска сбрасывается. `changed` уходит после
 каждого выбора, и страница сразу перезапрашивает выдачу.
 
-Список открывается так же, как у `SelectSingle`: в верхнем слое браузера, место,
+Список открывается так же, как у `SelectSingleFilter`: в верхнем слое браузера, место,
 высота, прокрутка и способы закрытия те же, фокус после закрытия возвращается
 на кнопку. Отличия: галочка стоит у каждого выбранного пункта; пункт
 сообщает скринридеру, выбран ли он (`aria-pressed`).
-Как и у `SelectSingle`, без пунктов кнопки нет, заголовок остаётся. Пункты
-пропали при открытом списке — список закрывается, запрос поиска сбрасывается,
-а вернувшиеся пункты появляются с закрытым списком.
+Как и у `SelectSingleFilter`, без пунктов кнопки нет, а заголовок, высота
+и рамка остаются. Пункты пропали при открытом списке — список закрывается,
+запрос поиска сбрасывается, а вернувшиеся пункты появляются с закрытым списком.
 
-С клавиатуры, пока список открыт, всё как у `SelectSingle`: стрелки вверх и вниз
-ведут фокус по пунктам по кругу, Enter или пробел переключают пункт и закрывают
-список, Escape закрывает его без выбора. Если выбрано несколько пунктов,
-отсчёт идёт от первого выбранного среди видимых. Мышь ведёт тот же фокус, что
-и стрелки: движение по пункту ставит фокус на него, подсвечен всегда один пункт.
+С клавиатуры, пока список открыт, всё как у `SelectSingleFilter`: стрелки вверх
+и вниз ведут фокус по пунктам по кругу, Enter или пробел переключают пункт и
+закрывают список, Escape закрывает его без выбора. Если выбрано несколько
+пунктов, отсчёт идёт от первого выбранного среди видимых. Наведение подсвечивает
+пункт, но фокус не двигает: фокус меняют клавиатура и клик, пункт под мышью и
+пункт в фокусе могут быть подсвечены одновременно.
 
 С `with-search` над пунктами стоит поле поиска: при прокрутке длинного списка
 оно остаётся на месте. Имя пункта должно содержать запрос, регистр не важен,
@@ -385,21 +526,52 @@ 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`
+остальные атрибуты уходят на поле ввода).
+
 ### InfoPill
 
 Пилюля, которая только показывает текст: статус, счётчик, флаг, пометку.
@@ -621,13 +793,16 @@ exportOrders() {
 таблицы и изменением размера окна. Открытие другого меню закрывает
 предыдущее.
 
-Пока меню открыто, стрелки вверх и вниз переводят фокус по пунктам и
-страницу не прокручивают: вниз — на первый пункт, вверх — на последний,
-дальше — по соседним, с краёв — по кругу. Enter на пункте под фокусом
-выбирает его. Подсветка пункта — это фокус, и мышь ведёт тот же фокус:
-движение по пункту ставит фокус на него, стрелки продолжают от пункта под
-курсором. Подсвечен всегда один пункт — тот, на который последними указали
-клавиатура или мышь.
+Пока меню открыто, стрелки вверх и вниз переводят фокус по пунктам и страницу не
+прокручивают: вниз — на первый пункт, вверх — на последний, дальше — по
+соседним, с краёв — по кругу. Enter на пункте под фокусом выбирает его.
+Наведение подсвечивает пункт, но фокус не двигает: фокус меняют клавиатура и
+клик. Пункт под мышью и пункт в фокусе с клавиатуры могут быть подсвечены
+одновременно; стрелки продолжают от пункта в фокусе.
+
+После закрытия меню фокус возвращается на стрелку, если он был внутри меню и
+после закрытия потерян. Фокус, который перешёл на другой элемент (например, в
+модалку, открытую пунктом), сохраняется.
 
 ### HamburgerMenu
 
@@ -673,9 +848,15 @@ Escape, клик по пункту, прокрутка и изменение р
 с `<hamburger-menu>` — `class`, `style`, `data-*` — ложатся на обёртку
 кнопки.
 
-Клавиатура и мышь — как в меню `DropdownButtonWithAction`: пока меню
-открыто, стрелки вверх и вниз переводят фокус по пунктам, Enter выбирает
-пункт под фокусом; подсветка пункта — это фокус, и мышь ведёт тот же фокус.
+Клавиатура и мышь — как в меню `DropdownButtonWithAction`: пока меню открыто,
+стрелки вверх и вниз переводят фокус по пунктам, Enter выбирает пункт под
+фокусом; наведение подсвечивает пункт, но фокус не двигает: фокус меняют
+клавиатура и клик, а пункт под мышью и пункт в фокусе могут быть подсвечены
+одновременно.
+
+После закрытия меню фокус возвращается на кнопку меню, если он был внутри меню
+и после закрытия потерян. Фокус, который перешёл на другой элемент (например, в
+модалку, открытую пунктом), сохраняется.
 
 ### DataTable
 
@@ -1006,12 +1187,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 |
@@ -1019,8 +1200,9 @@ rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: фор
 | `TextPopover` — подпись кнопки и имя области | Показать текст / Полный текст | Show text / Full text |
 
 Формат даты — `дд.мм.гггг` в обоих языках: это формат значения, а не текст.
-Неделя начинается с понедельника. Календари `SelectDateInterval` берут язык
-при монтировании: смена языка после монтирования в них не отражается.
+Неделя начинается с понедельника. Календари `SelectDateFilter`, `SelectDateForm`,
+`SelectDateIntervalFilter` и `SelectDateIntervalForm` берут язык при монтировании: смена языка после
+монтирования в них не отражается.
 
 ## Клавиатурная навигация
 
@@ -1038,7 +1220,7 @@ Vimium, Vimari, Vimlike — по их подсказкам, как мышью;
 выбирают только момент. Поля, крестик `NotificationMessage`, кнопки
 `ConfirmationModal` и `DropdownButtonWithAction` показывают фокус при любом
 его появлении, в том числе после клика мышью; остальные кнопки и ссылки —
-только с клавиатуры. Стрелки месяцев и подпись месяца в календаре `PickDay`
+только с клавиатуры. Стрелки месяцев и подпись месяца в календаре поля даты
 берут тот же вид, когда фокус в них с клавиатуры.
 
 Vimlike (Safari на iPhone, iPad и Mac) считает кнопкой любой элемент
@@ -1048,17 +1230,19 @@ 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 и набрать дату.
+
+Подсказки Vimlike в открытых меню, списках `SelectSingleFilter`,
+`SelectSingleForm`, `SelectMultipleFilter` и `SelectMultipleForm` и календарях
+`SelectDateFilter`, `SelectDateForm`, `SelectDateIntervalFilter`
+и `SelectDateIntervalForm` не видны: Vimlike рисует
+их под верхним слоем браузера, в котором открываются эти панели. Vimium
+выводит свои подсказки в верхний слой, и у него такой проблемы нет. В Vimlike
+панель открывают подсказкой её кнопки, а дальше выбирают стрелками и Enter:
+пункт списка или меню, день календаря.
 
 ## SSR
 
@@ -1069,8 +1253,10 @@ Inertia SSR), а серверная разметка гидратируется
 - `PageCard` на сервере рисует крестик, только если задан `fallback-url`:
   адрес возврата известен только в браузере, и крестик, ведущий на него,
   появляется после монтирования;
-- `SelectDateInterval` загружает Pikaday в браузере при монтировании:
-  календари появляются, когда загрузка закончится;
+- `SelectDateFilter`, `SelectDateForm`, `SelectDateIntervalFilter`
+  и `SelectDateIntervalForm` загружают Pikaday в браузере при монтировании:
+  календари появляются, когда загрузка
+  закончится;
 - остальные компоненты рендерятся на сервере так же, как в браузере.
 
 ## Правила API пакета
@@ -1081,12 +1267,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`).
@@ -1142,10 +1329,10 @@ Inertia SSR), а серверная разметка гидратируется
 
 Правило пакета — значение через `v-model` — относится к состоянию, которое
 компонент меняет сам: меню `DropdownButtonWithAction` закрывается по клику
-вне, `SelectSingle` меняет выбор. `ConfirmationModal` свою видимость не меняет
-никогда. Обе кнопки и Escape только сообщают родителю решение пользователя,
-а закрыть модалку, оставить её открытой на время запроса или открыть
-следующую — решает родитель.
+вне, `SelectSingleFilter` меняет выбор. `ConfirmationModal` свою видимость
+не меняет никогда. Обе кнопки и Escape только сообщают родителю решение
+пользователя, а закрыть модалку, оставить её открытой на время запроса или
+открыть следующую — решает родитель.
 
 `v-model` обещал бы двустороннюю связь, которой нет, поэтому видимость
 передаётся пропом `isOpen`.
@@ -1164,12 +1351,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`. Он наследует её
@@ -1180,6 +1379,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
 
 | Было | Стало |