@boobooking/dashboard-ui-components 0.7.0 → 0.9.0

package/README.md

@@ -13,6 +13,30 @@ import '@boobooking/dashboard-ui-components/style.css'
 
 Стили пакета подключаются **до** стилей приложения.
 
+### Подключение к приложению
+
+Плагин `dashboardUi` задаёт язык и переход по ссылкам пакета. Оба параметра
+необязательны; без плагина компоненты русскоязычные, а ссылки — обычные `<a>`.
+
+```js
+import { dashboardUi } from '@boobooking/dashboard-ui-components'
+import { router } from '@inertiajs/vue3'
+
+createApp(App).use(dashboardUi, {
+    lang: 'en',
+    navigate: (href) => router.visit(href),
+})
+```
+
+- `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`.
+
 ## Требования
 
 Vue не ниже 3.5, ESM, сборщик, умеющий импорт CSS из пакета. Версия 3.5 нужна
@@ -24,10 +48,11 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 
 ## Компоненты
 
-Пакет экспортирует четырнадцать компонентов: `Popup`, `Dot`, `PickDay`,
+Пакет экспортирует семнадцать компонентов: `Popup`, `Dot`, `PickDay`,
 `RussianMobileFilter`, `Search`, `SelectDateInterval`, `SelectSingle`,
 `SmallBadge`, `ErrorMessages`, `Closer`, `DownloadLink`, `Modal`,
-`ConfirmationModal`, `DropdownButtonWithAction`. В архив пакета
+`ConfirmationModal`, `DropdownButtonWithAction`, `Pagination`,
+`NavigationMenuElement`, `PageCard` и плагин `dashboardUi`. В архив пакета
 (`files: ["dist"]`) исходники не
 попадают, поэтому контракт каждого компонента — здесь и в playground, а не в
 исходном коде.
@@ -79,6 +104,7 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 | `modelValue` | `String` | `""` | Текущая дата |
 | `withEraser` | `Boolean` | `true` | Показывать ли ластик очистки |
 | `placeholderText` | `String` | `""` | Текст подсказки в пустом поле |
+| `lang` | `String` | язык плагина | `"ru"` или `"en"`; календарь берёт язык при монтировании |
 
 События: `update:modelValue` — при выборе даты в календаре и при очистке
 (пустой строкой); `changed` — в тех же двух случаях, для использования наравне
@@ -144,6 +170,7 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 | `header` | `String` | обязателен | Подпись поля |
 | `isRequired` | `Boolean` | `false` | Пометка обязательности в заголовке |
 | `isLoading` | `Boolean` | `false` | Индикатор загрузки в заголовке |
+| `lang` | `String` | язык плагина | `"ru"` или `"en"`; действует и на подсказки полей, и на оба календаря |
 
 События: `update:dateFrom`, `update:dateTo` — на каждый выбор в
 соответствующем `PickDay`; `changed` — когда новое значение отличается от
@@ -218,7 +245,8 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 | Проп | Тип | По умолчанию | Описание |
 | --- | --- | --- | --- |
 | `url` | `String` | обязателен | Адрес файла |
-| `title` | `String` | `"Скачать"` | Подпись и всплывающая подсказка |
+| `title` | `String` | `null` | Подпись и всплывающая подсказка; без него — «Скачать» / «Download» по языку |
+| `lang` | `String` | язык плагина | `"ru"` или `"en"` |
 
 Событий нет.
 
@@ -254,6 +282,12 @@ Escape: видимостью управляет родитель, как у `Con
 `<modal>` попадают на полноэкранный корень, а не на панель: размер панели и
 атрибуты диалога вроде `aria-describedby` снаружи не задаются.
 
+Панель не обрезает содержимое, чтобы выпадающие списки и календари внутри
+модалки могли выходить за её край. Поэтому блок слота со своим фоном у края
+панели сам скругляет внешние углы — верхний `rounded-t-lg`, нижний
+`rounded-b-lg`, — иначе его квадратные углы закроют скругление панели. Так
+сделано у `ConfirmationModal`.
+
 ### ConfirmationModal
 
 Модалка подтверждения действия: заголовок, текст, кнопка действия и кнопка
@@ -275,8 +309,9 @@ Escape: видимостью управляет родитель, как у `Con
 | `type` | `String` | `"warning"` | `"warning"` (жёлтая) или `"dangerous"` (красная) |
 | `confirmationHeading` | `String` | `""` | Заголовок |
 | `confirmationText` | `String` | `""` | Текст под заголовком |
-| `cancelButtonText` | `String` | `"Отмена"` | Подпись кнопки отмены |
+| `cancelButtonText` | `String` | `null` | Подпись кнопки отмены; без него — «Отмена» / «Cancel» по языку |
 | `actionButtonText` | `String` | обязателен | Подпись кнопки действия |
+| `lang` | `String` | язык плагина | `"ru"` или `"en"` |
 
 События: `actionConfirmed` — по кнопке действия, `actionCanceled` — по кнопке
 отмены. Ни одна из кнопок модалку не закрывает — см. раздел «Почему у
@@ -296,12 +331,125 @@ ConfirmationModal нет v-model».
 | Проп | Тип | По умолчанию | Описание |
 | --- | --- | --- | --- |
 | `modelValue` | `Boolean` | `false` | Открыто ли меню |
+| `lang` | `String` | язык плагина | `"ru"` или `"en"` |
 
 Событие: `update:modelValue` — только когда меню открыл или закрыл сам
 компонент: клик по стрелке, клик вне меню, Escape. Значение, пришедшее от
 родителя, компонент принимает молча: ответное событие вернуло бы родителю его
 же решение. Без `v-model` меню работает само по себе.
 
+### Pagination
+
+Переход на предыдущую и следующую страницу и строка «Показаны результаты X - Y
+из Z» для списков на Laravel API Resource.
+
+    <pagination class="mt-6" :links="orders.links" :meta="orders.meta" />
+
+| Проп | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `links` | `Object` | обязателен | `{ prev, next }` — адреса соседних страниц или `null` |
+| `meta` | `Object` | обязателен | `{ from, to, total }` |
+| `lang` | `String` | язык плагина | `"ru"` или `"en"` |
+
+Если записей нет — `meta` не задан или `meta.total` не больше нуля, —
+компонент ничего не рисует. Строка «Показаны результаты» — только когда в
+`meta` есть числовые `from` и `to`. Кнопка — только при непустом адресе в
+`links.prev` / `links.next`; при `links: null` остаётся одна строка
+результатов. Ссылки — через `navigate` плагина. Событий нет.
+
+### NavigationMenuElement
+
+Пункт меню шапки: ссылка с подчёркиванием активного раздела.
+
+    <navigation-menu-element name="Заказы" :url="route('orders')" :is-active="isOrders" />
+
+| Проп | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `url` | `String` | обязателен | Адрес раздела |
+| `name` | `String` | обязателен | Подпись |
+| `isActive` | `Boolean` | `false` | Активный раздел |
+
+Ссылка — через `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` отступ равен нулю.
+
+Карточка не обрезает содержимое, как `Modal`: выпадающие списки и календари
+могут выходить за её край. Блок со своим фоном у края карточки скругляет свои
+углы сам — например, нижний блок строк: `overflow-hidden sm:rounded-b-lg`.
+
+Крестик доступен с клавиатуры: Tab, Enter, пробел; в порядке табуляции крестик
+идёт после содержимого карточки; при фокусе с клавиатуры
+вокруг него кольцо. Доступное имя — «Назад» / «Back».
+
+| Проп | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `lang` | `String` | язык плагина | `"ru"` или `"en"` |
+
+Событий нет.
+
+## Языки
+
+Тексты пакета есть на русском и английском. Язык компонента — проп `lang`, если
+он задан, иначе язык плагина `dashboardUi`, иначе русский. Явно переданный текст
+главнее языка: `cancel-button-text` у `ConfirmationModal`, `title` у
+`DownloadLink`.
+
+| Компонент | `ru` | `en` |
+| --- | --- | --- |
+| `ConfirmationModal` — кнопка отмены | Отмена | Cancel |
+| `DownloadLink` — подпись | Скачать | Download |
+| `DropdownButtonWithAction` — подпись стрелки для скринридера | Открыть меню | Open menu |
+| `PickDay` — месяцы, дни недели, кнопки календаря | по-русски | in English |
+| `SelectDateInterval` — подсказки полей | от / до | from / to |
+| `Pagination` | Предыдущая / Следующая / Показаны результаты X - Y из Z | Previous / Next / Showing X - Y of Z results |
+| `PageCard` — доступное имя крестика | Назад | Back |
+
+Формат даты — `дд.мм.гггг` в обоих языках: это формат значения, а не текст.
+Неделя начинается с понедельника. Календарь `PickDay` берёт язык при
+монтировании: смена языка после монтирования в нём не отражается.
+
 ## Правила API пакета
 
 Компонент, добавляемый в пакет, следует тем же правилам, что и уже
@@ -332,6 +480,15 @@ ConfirmationModal нет v-model».
   префикса не сгенерируется. Классы в `:class` пишутся литералами — ключами
   объекта, ветками тернарного оператора, элементами массива. Оба правила
   проверяет `tests/utilityPrefix.test.js`.
+- Тексты интерфейса — только в `src/i18n.js`, в словарях `ru` и `en` с
+  одинаковыми ключами; компонент берёт их через миксин `withLang`
+  (`this.texts`) и получает проп `lang`.
+- Ссылка компонента — настоящий `<a href>`; обычный клик — через
+  `followLink($event, href)` миксина `withNavigation`, который отдаёт его
+  `navigate` плагина. Ни Inertia, ни роутер пакет не импортирует. Исключение —
+  `DownloadLink`: это обычная ссылка браузера, скачивающая файл, и через
+  `navigate` она не идёт. Через `navigate` ходят `Pagination` и
+  `NavigationMenuElement`.
 
 ## Почему у Popup и Dot нет события changed
 
@@ -366,7 +523,7 @@ ConfirmationModal нет v-model».
 
     npm run playground
 
-Поднимает демо-страницы со всеми четырнадцатью компонентами в двух окружениях:
+Поднимает демо-страницы со всеми семнадцатью компонентами в двух окружениях:
 голом (без Tailwind и стилей приложения) и в окружении приложения (с
 Tailwind, `@tailwindcss/forms` и типографикой, как у потребителя). Это
 основной способ посмотреть, как компоненты выглядят и ведут себя, а не
@@ -379,8 +536,8 @@ Tailwind, `@tailwindcss/forms` и типографикой, как у потре
 которое типографику не задаёт, компоненты отрисуются браузерными умолчаниями:
 рабочими, но чужими на вид.
 
-Компоненты русскоязычные: названия месяцев, подписи и правила номера телефона
-зашиты.
+Правила номера телефона в `RussianMobileFilter` — российские; язык текстов
+задаётся, см. «Языки».
 
 ## Ограничение