@boobooking/dashboard-ui-components 0.9.0 → 0.10.1

package/README.md

@@ -28,14 +28,18 @@ createApp(App).use(dashboardUi, {
 })
 ```
 
-- `lang` — `'ru'` (по умолчанию) или `'en'`; другое значение — ошибка в `app.use`.
+- `lang` — `'ru'` (по умолчанию) или `'en'`; другое значение — ошибка в
+  `app.use`.
 - `navigate(href)` — переход приложения по адресу: для Inertia
   `router.visit(href)`, для Vue Router `router.push(href)`. Компоненты рисуют
   настоящий `<a href>` и отдают `navigate` только обычный клик левой кнопкой;
   клики с Ctrl/Cmd/Shift/Alt, средней кнопкой и ссылки с `target` остаются
   браузеру. Без `navigate` браузер идёт по ссылке сам.
 
-`navigate` получает адрес ровно таким, каким он лежит в компоненте: `Pagination` отдаёт `links` Laravel как есть, а это абсолютные URL. С Vue Router приложение само превращает их в маршрут, например `new URL(href).pathname + search`, и только потом зовёт `router.push`.
+`navigate` получает адрес ровно таким, каким он лежит в компоненте:
+`Pagination` отдаёт `links` Laravel как есть, а это абсолютные URL. С Vue
+Router приложение само превращает их в маршрут, например
+`new URL(href).pathname + search`, и только потом зовёт `router.push`.
 
 ## Требования
 
@@ -50,12 +54,12 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 
 Пакет экспортирует семнадцать компонентов: `Popup`, `Dot`, `PickDay`,
 `RussianMobileFilter`, `Search`, `SelectDateInterval`, `SelectSingle`,
-`SmallBadge`, `ErrorMessages`, `Closer`, `DownloadLink`, `Modal`,
+`SmallBadge`, `ErrorMessages`, `Closer`, `DownloadLink`,
 `ConfirmationModal`, `DropdownButtonWithAction`, `Pagination`,
-`NavigationMenuElement`, `PageCard` и плагин `dashboardUi`. В архив пакета
-(`files: ["dist"]`) исходники не
-попадают, поэтому контракт каждого компонента — здесь и в playground, а не в
-исходном коде.
+`NavigationMenuElement`, `PageCard`, `NotificationMessage` и плагин
+`dashboardUi`. В архив пакета (`files: ["dist"]`) исходники не попадают,
+поэтому контракт каждого компонента — здесь и в playground, а не в исходном
+коде.
 
 ### Popup
 
@@ -250,44 +254,6 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 
 Событий нет.
 
-### Modal
-
-Оболочка модального окна: оверлей, панель и переходы открытия и закрытия.
-Заголовок, текст и кнопки кладёт в слот приложение. На этой оболочке построен
-`ConfirmationModal`.
-
-    <modal :is-open="isOpen" :heading-id="headingId">
-        <h3 :id="headingId">Заголовок</h3>
-        …содержимое…
-    </modal>
-
-| Проп | Тип | По умолчанию | Описание |
-| --- | --- | --- | --- |
-| `isOpen` | `Boolean` | `false` | Открыта ли модалка |
-| `headingId` | `String` | обязателен | `id` заголовка в слоте: им модалка подписывает диалог через `aria-labelledby` |
-
-Событий нет. Модалка не закрывается сама ни по клику на оверлей, ни по
-Escape: видимостью управляет родитель, как у `ConfirmationModal`. `id`
-заголовка удобно получать через `useId()` — тогда у двух модалок на одной
-странице он не совпадёт.
-
-Содержимое слота смонтировано всегда, а закрытая модалка его только прячет
-(`v-show`). Поэтому состояние внутри — выбор, введённый текст, ошибки —
-переживает закрытие, и сбрасывать его должен родитель.
-
-Панель белая, со скруглением `rounded-lg` и без внутренних отступов: их
-задаёт содержимое слота. На узком экране панель прижата к нижнему краю, а её
-ширина — по содержимому, но не больше экрана за вычетом полей; начиная с `sm`
-панель стоит по центру и занимает `max-w-lg`. `class` и другие атрибуты на
-`<modal>` попадают на полноэкранный корень, а не на панель: размер панели и
-атрибуты диалога вроде `aria-describedby` снаружи не задаются.
-
-Панель не обрезает содержимое, чтобы выпадающие списки и календари внутри
-модалки могли выходить за её край. Поэтому блок слота со своим фоном у края
-панели сам скругляет внешние углы — верхний `rounded-t-lg`, нижний
-`rounded-b-lg`, — иначе его квадратные углы закроют скругление панели. Так
-сделано у `ConfirmationModal`.
-
 ### ConfirmationModal
 
 Модалка подтверждения действия: заголовок, текст, кнопка действия и кнопка
@@ -317,6 +283,13 @@ Escape: видимостью управляет родитель, как у `Con
 отмены. Ни одна из кнопок модалку не закрывает — см. раздел «Почему у
 ConfirmationModal нет v-model».
 
+Панель модалки — белая, со скруглением `rounded-lg`: на узком экране прижата
+к нижнему краю, начиная с `sm` стоит по центру и занимает `max-w-lg`. `class` и
+другие атрибуты на `<confirmation-modal>` попадают на полноэкранный корень, а
+не на панель. Панель не обрезает содержимое, поэтому блоки текста и кнопок со
+своим фоном скругляют внешние углы сами — верхний `rounded-t-lg`, нижний
+`rounded-b-lg`.
+
 ### DropdownButtonWithAction
 
 Кнопка с меню дополнительных действий: основная часть — слот `button`, стрелка
@@ -415,9 +388,10 @@ sm:rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: ф
 `padding-right: var(--bb-closer-space)`, а в Tailwind 3 —
 `pr-[var(--bb-closer-space)]`. Вне `PageCard` отступ равен нулю.
 
-Карточка не обрезает содержимое, как `Modal`: выпадающие списки и календари
-могут выходить за её край. Блок со своим фоном у края карточки скругляет свои
-углы сам — например, нижний блок строк: `overflow-hidden sm:rounded-b-lg`.
+Карточка не обрезает содержимое, как у `ConfirmationModal`: выпадающие списки
+и календари могут выходить за её край. Блок со своим фоном у края карточки
+скругляет свои углы сам — например, нижний блок строк:
+`overflow-hidden sm:rounded-b-lg`.
 
 Крестик доступен с клавиатуры: Tab, Enter, пробел; в порядке табуляции крестик
 идёт после содержимого карточки; при фокусе с клавиатуры
@@ -429,6 +403,47 @@ sm:rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: ф
 
 Событий нет.
 
+### NotificationMessage
+
+Всплывающее уведомление: заголовок, текст, иконка по типу и крестик закрытия.
+На узком экране стоит снизу по центру, начиная с `sm` — в правом верхнем углу.
+
+    <notification-message
+        v-model="message"
+        type="confirmation"
+        notification-heading="Письмо отправлено"
+    />
+
+| Проп | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `modelValue` | `String` | `""` | Текст уведомления; пустая строка или `null` — уведомления нет |
+| `type` | `String` | `"warning"` | `"confirmation"` (галочка, серый фон), `"warning"` (жёлтое) или `"dangerous"` (красное) |
+| `notificationHeading` | `String` | `""` | Заголовок |
+| `lang` | `String` | язык плагина | `"ru"` или `"en"` |
+
+Уведомление показано, пока текст непуст. Крестик закрывает его сам — эмитит
+`update:modelValue` с пустой строкой, поэтому странице достаточно `v-model`.
+Других событий нет.
+
+Для скринридера уведомление — живая область: `role="alert"` у `dangerous`,
+`role="status"` у остальных. Область есть на странице всегда, а пустая
+невидима и не перехватывает клики. Скринридер объявляет текст, который
+появился после монтирования компонента; текст, уже стоявший при монтировании,
+может остаться необъявленным. Роль задаётся типом, поэтому `type` стоит менять
+только пока текст пуст — проще всего держать по экземпляру на каждый тип.
+Показывайте одно уведомление за раз: все они стоят в одном углу. Подпись
+крестика для скринридера — «Закрыть» / «Close». После закрытия с клавиатуры
+фокус не возвращается и уходит на `body` страницы.
+
+Корень — на весь экран (`fixed inset-0`), с ресетом пакета; слотов нет.
+
+У корня нет `z-index`, поэтому среди позиционированных элементов он рисуется в
+порядке DOM: ставьте компонент в разметке страницы последним. Под открытой
+модалкой или выпадающим меню пакета (их подложки — `z-20`) уведомление скрыто,
+а его крестик не нажимается, поэтому закрывайте модалку, прежде чем показать
+уведомление. `class` и атрибуты попадают на корень на весь экран, так что
+страница может поднять его своим классом, например `class="z-30"`.
+
 ## Языки
 
 Тексты пакета есть на русском и английском. Язык компонента — проп `lang`, если
@@ -445,6 +460,7 @@ sm:rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: ф
 | `SelectDateInterval` — подсказки полей | от / до | from / to |
 | `Pagination` | Предыдущая / Следующая / Показаны результаты X - Y из Z | Previous / Next / Showing X - Y of Z results |
 | `PageCard` — доступное имя крестика | Назад | Back |
+| `NotificationMessage` — подпись крестика для скринридера | Закрыть | Close |
 
 Формат даты — `дд.мм.гггг` в обоих языках: это формат значения, а не текст.
 Неделя начинается с понедельника. Календарь `PickDay` берёт язык при
@@ -561,8 +577,11 @@ Tailwind, `@tailwindcss/forms` и типографикой, как у потре
 такие обращения перестанут находить элементы: внутренние классы в контракт
 пакета не входят.
 
+С версии 0.10.0 `Modal` не экспортируется: это внутренняя оболочка
+`ConfirmationModal`.
+
 Ресет пакета распространяется и на содержимое слотов — разметку приложения
-внутри `Popup`, `DropdownButtonWithAction` и `Modal`. Ресет лежит в слое
+внутри `Popup` и `DropdownButtonWithAction`. Ресет лежит в слое
 `components`, поэтому внутри слота он сильнее всего, что приложение объявило
 в слое `base`: preflight, `@tailwindcss/forms` и собственных умолчаний
 приложения. В слоте он задаёт:
@@ -590,6 +609,6 @@ focus:ring-offset-2`.
 (`tabindex="-1"`): скринридер его не назовёт, а с клавиатуры до него не
 добраться.
 
-`Modal` и построенный на нём `ConfirmationModal` не переносят фокус внутрь при
-открытии, не удерживают его внутри, не возвращают на прежнее место после
-закрытия и не закрываются по Escape.
+`ConfirmationModal` не переносит фокус внутрь при открытии, не удерживает его
+внутри, не возвращает на прежнее место после закрытия и не закрывается по
+Escape.