@boobooking/dashboard-ui-components 0.16.3 → 0.17.1

package/README.md

@@ -90,12 +90,12 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 
 ## Компоненты
 
-Пакет экспортирует шестнадцать компонентов: `Dot`, `RussianMobileFilter`,
+Пакет экспортирует семнадцать компонентов: `Dot`, `RussianMobileFilter`,
 `Search`, `SelectDateInterval`, `SelectSingle`, `InfoPill`,
 `ErrorMessages`, `ActionPill`, `ConfirmationModal`,
 `DropdownButtonWithAction`, `HamburgerMenu`, `DataTable`,
-`NavigationMenuElement`, `PageCard`, `NotificationMessage`, `TextPopover`,
-функцию `downloadFile` и плагин `dashboardUi`. В архив пакета
+`NavigationMenuElement`, `PageTabs`, `PageCard`, `NotificationMessage`,
+`TextPopover`, функцию `downloadFile` и плагин `dashboardUi`. В архив пакета
 (`files: ["dist"]`) исходники не попадают, поэтому контракт каждого
 компонента — здесь и в playground, а не в исходном коде.
 
@@ -396,15 +396,21 @@ exportOrders() {
 | `lang` | `String` | язык плагина | `"ru"` или `"en"` |
 
 События: `actionConfirmed` — по кнопке действия, `actionCanceled` — по кнопке
-отмены. Ни одна из кнопок модалку не закрывает — см. раздел «Почему у
-ConfirmationModal нет v-model».
-
-Панель модалки — белая, со скруглением `rounded-lg`: на узком экране прижата
-к нижнему краю, начиная с `sm` стоит по центру и занимает `max-w-lg`. `class` и
-другие атрибуты на `<confirmation-modal>` попадают на полноэкранный корень, а
-не на панель. Панель не обрезает содержимое, поэтому блоки текста и кнопок со
-своим фоном скругляют внешние углы сами — верхний `rounded-t-lg`, нижний
-`rounded-b-lg`.
+отмены и по Escape. Ни одна из кнопок модалку не закрывает — см. раздел
+«Почему у ConfirmationModal нет v-model».
+
+Панель модалки — белая, со скруглением `rounded-lg`, стоит по центру и
+занимает `max-w-lg`. `class` и другие атрибуты на `<confirmation-modal>`
+попадают на полноэкранный корень, а не на панель. Панель не обрезает
+содержимое, поэтому блоки текста и кнопок со своим фоном скругляют внешние
+углы сами — верхний `rounded-t-lg`, нижний `rounded-b-lg`.
+
+Открытая модалка держит фокус: в первом кадре после открытия он встаёт на
+кнопку отмены, Tab и Shift+Tab ходят по её кнопкам по кругу, Escape —
+`actionCanceled`, как кнопка отмены. После закрытия фокус возвращается туда,
+где был до открытия, если страница не поставила его в другое место и тот
+элемент ещё на странице. Кадр нужен модалкам, которые открывает пункт меню:
+меню закрывается позже в том же клике и возвращает фокус на свою кнопку.
 
 ### DropdownButtonWithAction
 
@@ -621,12 +627,39 @@ Escape, клик по пункту, прокрутка и изменение р
 
 Ссылка — через `navigate` плагина. Событий нет.
 
+### PageTabs
+
+Табы второго уровня: ссылки на страницы одного раздела под шапкой —
+«Активные / Архив», «Ордера / Сертификаты / Sms».
+
+    <page-tabs :tabs="tabs" :active-key="activeTab" />
+
+    tabs() {
+        return [
+            { key: 'active', name: 'Активные', url: route('events') },
+            { key: 'archive', name: 'Архив', url: route('archive') },
+        ];
+    },
+
+| Проп | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `tabs` | `Array` | обязателен | `[{ key, name, url }]`: ключ, подпись и адрес таба — строки |
+| `activeKey` | `String` | `null` | Ключ открытого таба |
+| `lang` | `String` | язык плагина | `"ru"` или `"en"` — имя навигации для скринридера |
+
+Ключ сравнивается с `activeKey` строго, поэтому ключи — строки. Открытый
+таб выделен фоном и `aria-current="page"`; если ключа нет в списке, не
+выделен ни один. Вид одинаков на любой ширине: ссылки в строку, без
+переноса. Отступы вокруг и кнопки рядом — разметка страницы.
+
+Ссылки — через `navigate` плагина. Событий нет.
+
 ### PageCard
 
 Карточка отдельной страницы — формы или просмотра записи — по центру
 с крестиком, который ведёт туда, откуда карточку открыли.
 
-    <page-card class="px-4 pt-4 sm:px-6 sm:pt-6" :fallback-url="route('users')">
+    <page-card class="px-6 pt-6" :fallback-url="route('users')">
         <h3 class="pr-(--bb-closer-space) text-lg font-medium">Создание администратора</h3>
         …поля формы…
     </page-card>
@@ -634,10 +667,10 @@ Escape, клик по пункту, прокрутка и изменение р
 Страница просмотра, у секций которой свои отступы:
 
     <page-card :fallback-url="route('payments')">
-        <div class="px-4 py-5 border-b border-gray-200 sm:px-6">
+        <div class="px-6 py-5 border-b border-gray-200">
             <h3 class="pr-(--bb-closer-space) text-lg font-medium">{{ name }}</h3>
         </div>
-        <div class="overflow-hidden sm:rounded-b-lg">…строки…</div>
+        <div class="overflow-hidden rounded-b-lg">…строки…</div>
     </page-card>
 
 **Куда ведёт крестик.** Плагин `dashboardUi` с `currentUrl` (см.
@@ -667,7 +700,7 @@ Inertia с общим ключом окна:
             width: '7xl',
             windowKey: `group:${props.group.data.uuid}`,
             fallbackUrl: route('groups'),
-            class: 'px-4 py-4 sm:px-6 sm:py-6',
+            class: 'px-6 py-6',
         }],
     }
 
@@ -699,7 +732,7 @@ Inertia с общим ключом окна:
 которого крестик стоит снаружи, на `1rem` правее её края; ниже порога —
 в правом верхнем углу:
 
-| `width` | Ширина от `sm` | Крестик снаружи |
+| `width` | Ширина | Крестик снаружи |
 | --- | --- | --- |
 | `xl` (по умолчанию) | `max-w-xl` (36rem) | от `md` |
 | `4xl` | `max-w-4xl` (56rem) | от `lg` |
@@ -716,7 +749,7 @@ Inertia с общим ключом окна:
 `pr-[var(--bb-closer-space)]`. Вне `PageCard` отступ равен нулю.
 
 **Атрибуты.** Карточка — `relative my-6 mx-auto bg-white shadow-xl
-sm:rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: форма
+rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: форма
 передаёт их классом на корень, страница просмотра — не передаёт. На корень
 попадают `class`, `style`, `data-*` и `aria-*` приложения; классы
 приложения сильнее классов пакета. Остальные атрибуты, в том числе `id`,
@@ -730,7 +763,7 @@ sm:rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: ф
 Карточка не обрезает содержимое, как у `ConfirmationModal`: выпадающие
 списки и календари могут выходить за её край. Блок со своим фоном у края
 карточки скругляет свои углы сам — например, нижний блок строк:
-`overflow-hidden sm:rounded-b-lg`.
+`overflow-hidden rounded-b-lg`.
 
 Крестик доступен с клавиатуры: Tab, Enter, пробел; в порядке табуляции
 крестик идёт после содержимого карточки; при фокусе с клавиатуры вокруг
@@ -758,7 +791,7 @@ sm:rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: ф
 ### NotificationMessage
 
 Всплывающее уведомление: заголовок, текст, иконка по типу и крестик закрытия.
-На узком экране стоит снизу по центру, начиная с `sm` — в правом верхнем углу.
+Стоит в правом верхнем углу.
 
     <notification-message
         v-model="message"
@@ -835,6 +868,7 @@ sm:rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: ф
 | `SelectDateInterval` — подсказки полей | от / до | from / to |
 | Ластик `Search`, `RussianMobileFilter`, `SelectSingle` (язык плагина) и `SelectDateInterval` — подпись для скринридера | Очистить | Clear |
 | `DataTable` — пагинация | Предыдущая / Следующая / Показаны результаты X - Y из Z | Previous / Next / Showing X - Y of Z results |
+| `PageTabs` — имя навигации для скринридера | Закладки | Tabs |
 | `PageCard` — доступное имя крестика | Назад | Back |
 | `NotificationMessage` — подпись крестика для скринридера | Закрыть | Close |
 | `TextPopover` — подпись кнопки и имя области | Показать текст / Полный текст | Show text / Full text |
@@ -919,8 +953,8 @@ Inertia SSR), а серверная разметка гидратируется
 - Ссылка компонента — настоящий `<a href>`; обычный клик — через
   `followLink($event, href)` миксина `withNavigation`, который отдаёт его
   `navigate` плагина. Ни Inertia, ни роутер пакет не импортирует. Через `navigate` ходят
-  `DataTable` (его пагинация), `NavigationMenuElement`, основная
-  кнопка-переход и пункты-переходы `DropdownButtonWithAction` и
+  `DataTable` (его пагинация), `NavigationMenuElement`, `PageTabs`,
+  основная кнопка-переход и пункты-переходы `DropdownButtonWithAction` и
   пункты-переходы `HamburgerMenu`. Крестик `PageCard` — кнопка, а не ссылка:
   адрес возврата он тоже отдаёт `navigate`.
 - Компонент обращается к `window`, `document` и другим API браузера только
@@ -929,6 +963,11 @@ Inertia SSR), а серверная разметка гидратируется
   загружается и рендерится на сервере (см. «SSR»). Правило проверяют
   `tests/ssr.test.js` и `tests/hydration.test.js`: каждый экспортируемый
   компонент обязан иметь фикстуру в `tests/ssrFixtures.js`.
+- Мобильных вариантов у компонентов нет: дашборды работают на десктопе,
+  и компонент на любой ширине выглядит так, как на десктопе. Порог ширины
+  (`bb:sm:`, `bb:md:`, …) ставится, только если без него компонент
+  не помещается в узкое окно десктопа, — как у крестика `PageCard`,
+  который от порога выходит за край карточки.
 
 ## Почему у Dot нет события changed
 
@@ -946,18 +985,28 @@ Inertia SSR), а серверная разметка гидратируется
 Правило пакета — значение через `v-model` — относится к состоянию, которое
 компонент меняет сам: меню `DropdownButtonWithAction` закрывается по клику
 вне, `SelectSingle` меняет выбор. `ConfirmationModal` свою видимость не меняет
-никогда. Обе кнопки только сообщают родителю решение пользователя, а закрыть
-модалку, оставить её открытой на время запроса или открыть следующую — решает
-родитель.
+никогда. Обе кнопки и Escape только сообщают родителю решение пользователя,
+а закрыть модалку, оставить её открытой на время запроса или открыть
+следующую — решает родитель.
 
 `v-model` обещал бы двустороннюю связь, которой нет, поэтому видимость
 передаётся пропом `isOpen`.
 
+## Почему у PageTabs нет v-model
+
+Открытый таб `PageTabs` сам не меняет: клик по ссылке ведёт на другую
+страницу, и открытый таб приносит она — пропом `activeKey`. Пока новая
+страница не пришла, выделен прежний таб, как у пунктов шапки
+`NavigationMenuElement`.
+
+`v-model` обещал бы, что компонент меняет значение сам, поэтому открытый
+таб передаётся пропом `activeKey`.
+
 ## Playground
 
     npm run playground
 
-Поднимает демо-страницы со всеми шестнадцатью компонентами в двух окружениях:
+Поднимает демо-страницы со всеми семнадцатью компонентами в двух окружениях:
 голом (без Tailwind и стилей приложения) и в окружении приложения (с
 Tailwind, `@tailwindcss/forms` и типографикой, как у потребителя). Это
 основной способ посмотреть, как компоненты выглядят и ведут себя, а не
@@ -1258,7 +1307,3 @@ exportOrders() {
 Например, чекбоксу: `border border-gray-300 bg-white text-indigo-600
 checked:bg-current checked:border-transparent focus:ring-2
 focus:ring-offset-2`.
-
-`ConfirmationModal` не переносит фокус внутрь при открытии, не удерживает его
-внутри, не возвращает на прежнее место после закрытия и не закрывается по
-Escape.