@boobooking/dashboard-ui-components 0.20.0 → 0.21.0

package/README.md

@@ -92,11 +92,12 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 
 ## Компоненты
 
-Пакет экспортирует двадцать четыре компонента: `Dot`, `RussianMobileFilter`,
+Пакет экспортирует двадцать шесть компонентов: `Dot`, `RussianMobileFilter`,
 `Search`, `SelectDateFilter`, `SelectDateForm`, `SelectDateIntervalFilter`,
 `SelectDateIntervalForm`,
 `SelectSingleFilter`, `SelectSingleForm`, `SelectMultipleFilter`,
-`SelectMultipleForm`, `InfoPill`, `ErrorMessages`, `FormInput`, `ActionPill`,
+`SelectMultipleForm`, `SelectSingleCards`, `SelectMultipleList`, `InfoPill`,
+`ErrorMessages`, `FormInput`, `ActionPill`,
 `ConfirmationModal`, `DropdownButtonWithAction`, `HamburgerMenu`, `DataTable`,
 `NavigationMenuElement`, `PageTabs`, `PageCard`, `NotificationMessage`,
 `TextPopover`, функцию `downloadFile` и плагин `dashboardUi`. В архив пакета
@@ -572,6 +573,126 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 все остальные атрибуты и слушатели ложатся на корень компонента (у `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
 
 Пилюля, которая только показывает текст: статус, счётчик, флаг, пометку.
@@ -1216,10 +1337,14 @@ 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` показывают фокус при любом
-его появлении, в том числе после клика мышью; остальные кнопки и ссылки —
+его появлении, в том числе после клика мышью. Карточки `SelectSingleCards`,
+галочки `SelectMultipleList`, остальные кнопки и ссылки показывают фокус
 только с клавиатуры. Стрелки месяцев и подпись месяца в календаре поля даты
 берут тот же вид, когда фокус в них с клавиатуры.
 
@@ -1235,6 +1360,10 @@ Vimlike (Safari на iPhone, iPad и Mac) считает кнопкой любо
 внутри кнопки Vimlike считал бы кнопкой вместо неё. В поле по-прежнему можно
 перейти Tab и набрать дату.
 
+У карточки `SelectSingleCards` одна подсказка расширения на всей карточке,
+у галочки `SelectMultipleList` — одна на пункт. Safari на Mac без настройки
+Tab по всем объектам пропускает переключатели и галочки, как и кнопки пакета.
+
 Подсказки Vimlike в открытых меню, списках `SelectSingleFilter`,
 `SelectSingleForm`, `SelectMultipleFilter` и `SelectMultipleForm` и календарях
 `SelectDateFilter`, `SelectDateForm`, `SelectDateIntervalFilter`
@@ -1351,7 +1480,7 @@ Inertia SSR), а серверная разметка гидратируется
 
     npm run playground
 
-Поднимает демо-страницы со всеми двадцатью четырьмя компонентами в двух окружениях:
+Поднимает демо-страницы со всеми двадцатью шестью компонентами в двух окружениях:
 голом (без Tailwind и стилей приложения) и в окружении приложения (с
 Tailwind, `@tailwindcss/forms` и типографикой, как у потребителя). Это
 основной способ посмотреть, как компоненты выглядят и ведут себя, а не