@boobooking/dashboard-ui-components 0.8.0 → 0.10.0

package/README.md

@@ -48,11 +48,11 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 
 ## Компоненты
 
-Пакет экспортирует шестнадцать компонентов: `Popup`, `Dot`, `PickDay`,
+Пакет экспортирует семнадцать компонентов: `Popup`, `Dot`, `PickDay`,
 `RussianMobileFilter`, `Search`, `SelectDateInterval`, `SelectSingle`,
-`SmallBadge`, `ErrorMessages`, `Closer`, `DownloadLink`, `Modal`,
+`SmallBadge`, `ErrorMessages`, `Closer`, `DownloadLink`,
 `ConfirmationModal`, `DropdownButtonWithAction`, `Pagination`,
-`NavigationMenuElement` и плагин `dashboardUi`. В архив пакета
+`NavigationMenuElement`, `PageCard`, `NotificationMessage` и плагин `dashboardUi`. В архив пакета
 (`files: ["dist"]`) исходники не
 попадают, поэтому контракт каждого компонента — здесь и в playground, а не в
 исходном коде.
@@ -250,44 +250,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 +279,13 @@ Escape: видимостью управляет родитель, как у `Con
 отмены. Ни одна из кнопок модалку не закрывает — см. раздел «Почему у
 ConfirmationModal нет v-model».
 
+Панель модалки — белая, со скруглением `rounded-lg`: на узком экране прижата
+к нижнему краю, начиная с `sm` стоит по центру и занимает `max-w-lg`. `class` и
+другие атрибуты на `<confirmation-modal>` попадают на полноэкранный корень, а
+не на панель. Панель не обрезает содержимое, поэтому блоки текста и кнопок со
+своим фоном скругляют внешние углы сами — верхний `rounded-t-lg`, нижний
+`rounded-b-lg`.
+
 ### DropdownButtonWithAction
 
 Кнопка с меню дополнительных действий: основная часть — слот `button`, стрелка
@@ -371,6 +340,105 @@ ConfirmationModal нет v-model».
 
 Ссылка — через `navigate` плагина. Событий нет.
 
+### PageCard
+
+Карточка отдельной страницы — формы или просмотра записи — по центру с
+крестиком «назад по истории».
+
+    <page-card class="px-4 pt-4 sm:px-6 sm:pt-6">
+        <h3 class="pr-(--bb-closer-space) text-lg font-medium">Создание администратора</h3>
+        …поля формы…
+    </page-card>
+
+Страница просмотра, у секций которой свои отступы:
+
+    <page-card>
+        <div class="px-4 py-5 border-b border-gray-200 sm:px-6">
+            <h3 class="pr-(--bb-closer-space) text-lg font-medium">{{ name }}</h3>
+        </div>
+        <div class="overflow-hidden sm:rounded-b-lg">…строки…</div>
+    </page-card>
+
+Карточка — `relative my-6 mx-auto bg-white shadow-xl sm:max-w-xl
+sm:rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: форма передаёт
+их классом на корень, страница просмотра — не передаёт. Классы и атрибуты
+приложения попадают на корень и сильнее классов пакета. Ресет пакета на
+карточку и её содержимое не распространяется: разметка страницы, в том числе
+поля `@tailwindcss/forms`, выглядит так же, как вне карточки.
+
+Крестик показан, если в истории вкладки больше одной записи
+(`history.length > 1`, значение читается при создании компонента), и по клику
+возвращает назад (`history.back()`). `PageCard` читает историю браузера при
+создании компонента, поэтому ему нужен браузер: серверный рендеринг (SSR) не
+поддерживается. `history.length` считает и записи впереди
+текущей, поэтому это не гарантия, что назад есть куда. От `md` крестик стоит
+снаружи карточки, на `1rem` правее её края; ниже `md` — в её правом верхнем
+углу. Порог рассчитан на карточку по центру области на всю ширину страницы: в
+узкой колонке или рядом с боковой панелью места снаружи может не хватить. Он
+рассчитан и на ширину карточки по умолчанию (`max-w-xl`, 36rem): если передать
+классом на корень более широкую, места снаружи тоже может не хватить.
+
+Заголовок оставляет место под крестик правым отступом из переменной
+`--bb-closer-space`: `3.5rem`, пока крестик в углу, `0` — когда он снаружи или
+его нет. В Tailwind это `pr-(--bb-closer-space)`; без Tailwind 4 — обычный CSS
+`padding-right: var(--bb-closer-space)`, а в Tailwind 3 —
+`pr-[var(--bb-closer-space)]`. Вне `PageCard` отступ равен нулю.
+
+Карточка не обрезает содержимое, как у `ConfirmationModal`: выпадающие списки и календари
+могут выходить за её край. Блок со своим фоном у края карточки скругляет свои
+углы сам — например, нижний блок строк: `overflow-hidden sm:rounded-b-lg`.
+
+Крестик доступен с клавиатуры: Tab, Enter, пробел; в порядке табуляции крестик
+идёт после содержимого карточки; при фокусе с клавиатуры
+вокруг него кольцо. Доступное имя — «Назад» / «Back».
+
+| Проп | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `lang` | `String` | язык плагина | `"ru"` или `"en"` |
+
+Событий нет.
+
+### 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`, если
@@ -386,6 +454,8 @@ ConfirmationModal нет v-model».
 | `PickDay` — месяцы, дни недели, кнопки календаря | по-русски | in English |
 | `SelectDateInterval` — подсказки полей | от / до | from / to |
 | `Pagination` | Предыдущая / Следующая / Показаны результаты X - Y из Z | Previous / Next / Showing X - Y of Z results |
+| `PageCard` — доступное имя крестика | Назад | Back |
+| `NotificationMessage` — подпись крестика для скринридера | Закрыть | Close |
 
 Формат даты — `дд.мм.гггг` в обоих языках: это формат значения, а не текст.
 Неделя начинается с понедельника. Календарь `PickDay` берёт язык при
@@ -464,7 +534,7 @@ ConfirmationModal нет v-model».
 
     npm run playground
 
-Поднимает демо-страницы со всеми шестнадцатью компонентами в двух окружениях:
+Поднимает демо-страницы со всеми семнадцатью компонентами в двух окружениях:
 голом (без Tailwind и стилей приложения) и в окружении приложения (с
 Tailwind, `@tailwindcss/forms` и типографикой, как у потребителя). Это
 основной способ посмотреть, как компоненты выглядят и ведут себя, а не
@@ -502,8 +572,10 @@ Tailwind, `@tailwindcss/forms` и типографикой, как у потре
 такие обращения перестанут находить элементы: внутренние классы в контракт
 пакета не входят.
 
+С версии 0.10.0 `Modal` не экспортируется: это внутренняя оболочка `ConfirmationModal`.
+
 Ресет пакета распространяется и на содержимое слотов — разметку приложения
-внутри `Popup`, `DropdownButtonWithAction` и `Modal`. Ресет лежит в слое
+внутри `Popup` и `DropdownButtonWithAction`. Ресет лежит в слое
 `components`, поэтому внутри слота он сильнее всего, что приложение объявило
 в слое `base`: preflight, `@tailwindcss/forms` и собственных умолчаний
 приложения. В слоте он задаёт:
@@ -531,6 +603,6 @@ focus:ring-offset-2`.
 (`tabindex="-1"`): скринридер его не назовёт, а с клавиатуры до него не
 добраться.
 
-`Modal` и построенный на нём `ConfirmationModal` не переносят фокус внутрь при
-открытии, не удерживают его внутри, не возвращают на прежнее место после
-закрытия и не закрываются по Escape.
+`ConfirmationModal` не переносит фокус внутрь при открытии, не удерживает его
+внутри, не возвращает на прежнее место после закрытия и не закрывается по
+Escape.