@boobooking/dashboard-ui-components 0.6.0 → 0.8.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` и плагин `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,66 @@ 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` плагина. Событий нет.
+
+## Языки
+
+Тексты пакета есть на русском и английском. Язык компонента — проп `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 |
+
+Формат даты — `дд.мм.гггг` в обоих языках: это формат значения, а не текст.
+Неделя начинается с понедельника. Календарь `PickDay` берёт язык при
+монтировании: смена языка после монтирования в нём не отражается.
+
 ## Правила API пакета
 
 Компонент, добавляемый в пакет, следует тем же правилам, что и уже
@@ -326,6 +415,21 @@ ConfirmationModal нет v-model».
   где ждут строку, объект или массив, он считает пустыми: пустой строкой,
   отсутствием сообщений, пустым списком. Для обязательного пропа Vue при этом
   предупредит о несовпадении типа, но компонент отрисуется.
+- Каждая утилита в разметке компонента пишется с префиксом `bb:` — в
+  `class`, в `:class` и в пропсах `*-class` у `<transition>`; варианты идут
+  после префикса: `bb:sm:inline-block`, `bb:hover:bg-red-700`. Утилита без
+  префикса не сгенерируется. Классы в `: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
 
@@ -360,7 +464,7 @@ ConfirmationModal нет v-model».
 
     npm run playground
 
-Поднимает демо-страницы со всеми четырнадцатью компонентами в двух окружениях:
+Поднимает демо-страницы со всеми шестнадцатью компонентами в двух окружениях:
 голом (без Tailwind и стилей приложения) и в окружении приложения (с
 Tailwind, `@tailwindcss/forms` и типографикой, как у потребителя). Это
 основной способ посмотреть, как компоненты выглядят и ведут себя, а не
@@ -373,15 +477,30 @@ Tailwind, `@tailwindcss/forms` и типографикой, как у потре
 которое типографику не задаёт, компоненты отрисуются браузерными умолчаниями:
 рабочими, но чужими на вид.
 
-Компоненты русскоязычные: названия месяцев, подписи и правила номера телефона
-зашиты.
+Правила номера телефона в `RussianMobileFilter` — российские; язык текстов
+задаётся, см. «Языки».
 
 ## Ограничение
 
-Пакет отдаёт скомпилированные утилиты Tailwind — те же имена классов, что
-генерирует Tailwind приложения. При стоковой палитре правила совпадают. Если
-приложение переопределит стоковый цвет, одноимённые правила столкнутся и
-победит подключённое позже, то есть компоненты возьмут палитру приложения.
+Утилиты пакета собраны с префиксом `bb`: классы внутри компонентов — вида
+`bb:flex` и `bb:sm:inline-block`, переменные темы — `--bb-*`. Tailwind
+приложения таких классов не генерирует, поэтому одноимённых правил у пакета и
+приложения нет: вид компонентов не зависит ни от того, какие утилиты
+генерирует приложение, ни от его палитры. Общими остаются только служебные
+переменные Tailwind `--tw-*` с их `@property` — на одной версии Tailwind у
+пакета и приложения они объявлены одинаково — и глобальный `@keyframes pulse`
+(его использует `bb:animate-pulse` у `Dot`): если приложение объявит свой
+`pulse`, победит тот, что подключён позже.
+
+Порядок «стили пакета до стилей приложения» по-прежнему нужен: классы,
+которые приложение передаёт на корень компонента, — его собственные
+утилиты, и при одинаковом свойстве они побеждают, потому что подключены
+позже.
+
+С версии 0.7.0 классы внутри компонентов — `bb:*`. Если приложение
+обращалось к внутренностям компонентов по классам в своём CSS или тестах,
+такие обращения перестанут находить элементы: внутренние классы в контракт
+пакета не входят.
 
 Ресет пакета распространяется и на содержимое слотов — разметку приложения
 внутри `Popup`, `DropdownButtonWithAction` и `Modal`. Ресет лежит в слое