@boobooking/dashboard-ui-components 0.15.1 → 0.16.0

package/README.md

@@ -65,31 +65,49 @@ Vue не ниже 3.5, ESM, сборщик, умеющий импорт CSS из
 Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в CSS приложения
 пакету не нужны.
 
-Меню `DropdownButtonWithAction` и `HamburgerMenu`, список `SelectSingle` и
-календари `SelectDateInterval` стоят на Popover API браузера: Safari 17+,
-Chrome 114+, Firefox 125+. В браузерах старше меню, список и календари
-видны в потоке всегда.
+Меню `DropdownButtonWithAction` и `HamburgerMenu`, список `SelectSingle`,
+календари `SelectDateInterval` и подсказка `TextPopover` стоят на Popover API
+браузера: Safari 17+, Chrome 114+, Firefox 125+. В браузерах старше меню,
+список, календари и подсказка видны в потоке всегда.
+
+## Цвета
+
+У пакета один список цветов, и все компоненты с цветом берут его:
+`gray`, `green`, `yellow`, `red`, `indigo`, `purple`. Цвет передаётся
+именем; другое имя валидатор отклоняет, а компонент рисуется без цвета.
+Смысл цвета — какой статус зелёный — задаёт проект своей картой
+«значение → имя».
+
+| Где | Вид цвета `<тон>` |
+| --- | --- |
+| `InfoPill`, `ActionPill` | фон `-100`, текст `-800`; у `ActionPill` при наведении текст `-600` |
+| основная кнопка и стрелка `DropdownButtonWithAction` | фон `-100`, рамка `-300`, текст `-800`, при наведении фон `-200` |
+| пункт меню `DropdownButtonWithAction` и `HamburgerMenu` | текст `-800`, в фокусе фон `-100` |
+| `Dot`, полоска строки `DataTable` | `-500` |
+
+Без цвета кнопка белая с серой рамкой, пункт меню серый, строка таблицы без
+полоски — это вид компонента по умолчанию, в список он не входит.
 
 ## Компоненты
 
-Пакет экспортирует пятнадцать компонентов: `Dot`, `RussianMobileFilter`,
-`Search`, `SelectDateInterval`, `SelectSingle`, `SmallBadge`,
-`ErrorMessages`, `DownloadLink`, `ConfirmationModal`,
+Пакет экспортирует шестнадцать компонентов: `Dot`, `RussianMobileFilter`,
+`Search`, `SelectDateInterval`, `SelectSingle`, `InfoPill`,
+`ErrorMessages`, `ActionPill`, `ConfirmationModal`,
 `DropdownButtonWithAction`, `HamburgerMenu`, `DataTable`,
-`NavigationMenuElement`, `PageCard`, `NotificationMessage` и плагин
-`dashboardUi`. В архив пакета (`files: ["dist"]`) исходники не попадают,
-поэтому контракт каждого компонента — здесь и в playground, а не в исходном
-коде.
+`NavigationMenuElement`, `PageCard`, `NotificationMessage`, `TextPopover`,
+функцию `downloadFile` и плагин `dashboardUi`. В архив пакета
+(`files: ["dist"]`) исходники не попадают, поэтому контракт каждого
+компонента — здесь и в playground, а не в исходном коде.
 
 ### Dot
 
-Индикатор-точка: красная или зелёная, с пульсацией или без.
+Индикатор-точка любого цвета из списка, с пульсацией или без.
 
     <dot color="green" :with-pulse="isLive" />
 
 | Проп | Тип | По умолчанию | Описание |
 | --- | --- | --- | --- |
-| `color` | `String` | обязателен | `"red"` или `"green"` |
+| `color` | `String` | обязателен | Имя из списка цветов (раздел «Цвета») |
 | `withPulse` | `Boolean` | `false` | Добавляет анимацию пульсации |
 
 Событий нет. Значения у `Dot` тоже нет — см. раздел
@@ -224,16 +242,17 @@ Chrome 114+, Firefox 125+. В браузерах старше меню, спис
 внутри списка — нет. Открытие другого списка, календаря или меню
 закрывает предыдущее.
 
-### SmallBadge
+### InfoPill
 
-Бейдж-пилюля с коротким текстом. Текст не переносится.
+Пилюля, которая только показывает текст: статус, счётчик, флаг, пометку.
+Текст не переносится.
 
-    <small-badge text="Отправлено" color="green" />
+    <info-pill text="доставлено" color="green" />
 
 | Проп | Тип | По умолчанию | Описание |
 | --- | --- | --- | --- |
-| `text` | `String` | обязателен | Текст бейджа |
-| `color` | `String` | обязателен | `"green"`, `"indigo"`, `"gray"`, `"blue"`, `"red"` или `"yellow"` |
+| `text` | `String` | обязателен | Текст пилюли |
+| `color` | `String` | обязателен | Имя из списка цветов |
 
 Событий нет.
 
@@ -251,19 +270,60 @@ Chrome 114+, Firefox 125+. В браузерах старше меню, спис
 
 Событий нет.
 
-### DownloadLink
+### ActionPill
 
-Ссылка на файл в виде бейджа с иконкой скачивания. Кликабелен весь бейдж.
+Пилюля, которой запускают действие: скачать отчёт, запросить статусы. Что
+делает действие, пилюля не знает — страница слушает `click` и сама передаёт
+`isLoading`, пока действие идёт.
 
-    <download-link :url="exportUrl" title="скачать xlsx" />
+    <action-pill
+        icon="download"
+        title="скачать xlsx"
+        loading-text="формируется отчёт"
+        :is-loading="exportLoading"
+        @click="exportOrders"
+    />
 
 | Проп | Тип | По умолчанию | Описание |
 | --- | --- | --- | --- |
-| `url` | `String` | обязателен | Адрес файла |
-| `title` | `String` | `null` | Подпись и всплывающая подсказка; без него — «Скачать» / «Download» по языку |
-| `lang` | `String` | язык плагина | `"ru"` или `"en"` |
+| `title` | `String` | обязателен | Подпись и всплывающая подсказка |
+| `icon` | `String` | обязателен | `"download"` или `"refresh"` |
+| `color` | `String` | `"purple"` | Имя из списка цветов |
+| `isLoading` | `Boolean` | `false` | Идёт работа |
+| `loadingText` | `String` | `null` | Подпись на время работы; без неё остаётся `title` |
 
-Событий нет.
+Событие: `click` без аргументов.
+
+Пока идёт работа, пилюля погашена и недоступна — второй клик не проходит,
+вместо иконки бегут стрелки часов, подпись — `loadingText`. При системной
+настройке «уменьшить движение» стрелки стоят. Иконки пакета — `download`
+и `refresh`; новое действие с новой иконкой — новая иконка в пакете.
+
+### downloadFile
+
+Функция: скачивает файл запросом и отдаёт его браузеру. Страница знает,
+когда файл пришёл, — так показывается работа на `ActionPill`.
+
+```js
+import { downloadFile } from '@boobooking/dashboard-ui-components'
+
+exportOrders() {
+    this.exportLoading = true;
+    downloadFile(this.exportUrl)
+        .catch(() => { this.exportFailure = "Попробуйте ещё раз"; })
+        .finally(() => { this.exportLoading = false; });
+}
+```
+
+- Запрос — `GET` с cookie сессии (`credentials: 'same-origin'`).
+- Promise отклоняется: при ответе не `2xx` (код в тексте ошибки), при
+  перенаправлении — обычно на страницу входа после истёкшей сессии — и при
+  сетевой ошибке.
+- Имя файла — из `Content-Disposition` (`filename*=UTF-8''…`, затем
+  `filename`), без него — последний сегмент пути адреса, без пути —
+  `download`.
+- Таймаута нет; уход со страницы скачивание не прерывает. Файл до
+  сохранения целиком в памяти вкладки.
 
 ### ConfirmationModal
 
@@ -331,7 +391,7 @@ ConfirmationModal нет v-model».
 | `label` | `String`, обязательно | Текст кнопки или пункта меню |
 | `href` | `String` | Переход: обычный клик уходит в `navigate` плагина `dashboardUi`, клик с Cmd/Ctrl/Shift и средней кнопкой — браузеру; без `navigate` — обычная ссылка |
 | `onSelect` | `Function` | Действие: вызывается без аргументов |
-| `color` | `"yellow"` или `"red"` | Цвет; без поля — обычный |
+| `color` | `String` | Имя из списка цветов; без поля — обычный |
 
 Основная кнопка работает как пункт меню: переход — ссылка, действие —
 кнопка, и `onSelect` вызывает сам компонент — по клику, Enter и пробелу.
@@ -339,10 +399,9 @@ ConfirmationModal нет v-model».
 разбираться в разметке компонента.
 
 Цвет первого действия красит основную кнопку вместе со стрелкой, цвет
-пункта меню — только этот пункт. Обычная кнопка — белая с серой рамкой,
-жёлтая и красная — светлый фон, рамка и текст своего цвета. Обычный пункт
-меню — серый текст, при подсветке серый фон; жёлтый и красный — текст
-своего цвета, при подсветке светлый фон того же цвета.
+пункта меню — только этот пункт. Без цвета кнопка белая с серой рамкой,
+пункт — серый текст и серый фон при подсветке; с цветом — по разделу
+«Цвета».
 
 Неверный список Vue отмечает предупреждением о пропе в режиме разработки,
 а компонент не падает: элементы-необъекты пропускает, кнопка без функции
@@ -404,7 +463,7 @@ ConfirmationModal нет v-model».
 
 Пункты, их проверка и вид — как у `DropdownButtonWithAction`: переход —
 `{ label, href }`, действие — `{ label, onSelect }`, цвет —
-`color: 'yellow'` или `color: 'red'`. Выход запросом DELETE — действие:
+`color: имя из списка цветов`. Выход запросом DELETE — действие:
 Inertia пакет не импортирует, `router.delete` вызывает страница.
 
 Событий и `v-model` нет: меню открывают и закрывают кнопка, клик вне меню,
@@ -441,10 +500,10 @@ Escape, клик по пункту, прокрутка и изменение р
         empty-text="Не найдено ордеров"
     >
         <template #results-actions>
-            <download-link :url="exportUrl" title="скачать xlsx" />
+            <action-pill icon="download" title="скачать xlsx" :is-loading="exportLoading" @click="exportOrders" />
         </template>
         <template #cell-status="{ row }">
-            <small-badge :text="row.statusLabel" :color="row.statusColor" />
+            <info-pill :text="row.statusLabel" :color="row.statusColor" />
         </template>
     </data-table>
 
@@ -467,7 +526,7 @@ Escape, клик по пункту, прокрутка и изменение р
 | `foundText` | `String` | `null` | «Найдено ордеров» → бейдж «Найдено ордеров: 100», когда записи есть |
 | `emptyText` | `String` | `null` | «Не найдено ордеров» — бейдж, когда записей нет |
 | `variant` | `String` | `"page"` | `"page"` — отдельная карточка с тенью; `"card"` — таблица внутри карточки страницы, только линия сверху |
-| `rowColor` | `Function` | `null` | `row => 'red' \| 'green' \| null` — цвет строки вместо полосатости |
+| `rowStripe` | `Function` | `null` | `row => имя цвета \| null` — полоска слева в первой ячейке строки; строки полосатые всегда |
 | `lang` | `String` | язык плагина | `"ru"` или `"en"` — тексты пагинации |
 
 Столбец:
@@ -692,17 +751,39 @@ sm:rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: ф
 уведомление. `class` и атрибуты попадают на корень на весь экран, так что
 страница может поднять его своим классом, например `class="z-30"`.
 
+### TextPopover
+
+Иконка-глаз, по клику — подсказка со скрытым текстом: длинный текст SMS,
+значение ключа. Пустой текст — компонента нет.
+
+    <text-popover :text="row.message" />
+
+| Проп | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `text` | `String` | обязателен | Скрытый текст; `null` и `""` — компонента нет |
+| `modelValue` | `Boolean` | `false` | Открыта ли подсказка; `v-model` необязателен |
+| `lang` | `String` | язык плагина | `"ru"` или `"en"` |
+
+Событие: `update:modelValue` — когда подсказка открылась или закрылась сама:
+кнопкой, кликом вне, Escape, прокруткой, изменением размера окна, опустевшим
+текстом. Значение, пришедшее от родителя, эхом не возвращается.
+
+Подсказка открывается в верхнем слое браузера (Popover API): правым краем по
+правому краю иконки, шириной до 384 px, вниз, если помещается, иначе туда,
+где места больше; длинный текст прокручивается внутри, в том числе с
+клавиатуры. Пока подсказка открыта, остальная страница не выделяется:
+тройной клик и протяжка мышью выделяют только её текст. У левого края окна
+подсказка сужается до места слева от иконки, как и меню.
+
 ## Языки
 
 Тексты пакета есть на русском и английском. Язык компонента — проп `lang`, если
 он задан, иначе язык плагина `dashboardUi`, иначе русский. Явно переданный текст
-главнее языка: `cancel-button-text` у `ConfirmationModal`, `title` у
-`DownloadLink`.
+главнее языка: `cancel-button-text` у `ConfirmationModal`.
 
 | Компонент | `ru` | `en` |
 | --- | --- | --- |
 | `ConfirmationModal` — кнопка отмены | Отмена | Cancel |
-| `DownloadLink` — подпись | Скачать | Download |
 | `DropdownButtonWithAction` — подпись стрелки для скринридера | Открыть меню | Open menu |
 | `HamburgerMenu` — подпись кнопки для скринридера | Открыть меню | Open menu |
 | `SelectDateInterval` — месяцы, дни недели, кнопки календарей | по-русски | in English |
@@ -710,6 +791,7 @@ sm:rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: ф
 | `DataTable` — пагинация | Предыдущая / Следующая / Показаны результаты X - Y из Z | Previous / Next / Showing X - Y of Z results |
 | `PageCard` — доступное имя крестика | Назад | Back |
 | `NotificationMessage` — подпись крестика для скринридера | Закрыть | Close |
+| `TextPopover` — подпись кнопки и имя области | Показать текст / Полный текст | Show text / Full text |
 
 Формат даты — `дд.мм.гггг` в обоих языках: это формат значения, а не текст.
 Неделя начинается с понедельника. Календари `SelectDateInterval` берут язык
@@ -756,20 +838,20 @@ Inertia SSR), а серверная разметка гидратируется
   `class`, в `:class` и в пропсах `*-class` у `<transition>`; варианты идут
   после префикса: `bb:sm:inline-block`, `bb:hover:bg-red-700`. Утилита без
   префикса не сгенерируется. Классы в `:class` пишутся литералами — ключами
-  объекта, ветками тернарного оператора, элементами массива. Оба правила
+  объекта, ветками тернарного оператора, элементами массива. Цветовые классы
+  компонент не пишет сам — берёт из `src/colors.js` вызовом
+  `colorClass(имя, набор)`, и эту форму тест тоже принимает. Оба правила
   проверяет `tests/utilityPrefix.test.js`.
 - Тексты интерфейса — только в `src/i18n.js`, в словарях `ru` и `en` с
   одинаковыми ключами; компонент берёт их через миксин `withLang`
   (`this.texts`) и получает проп `lang`.
 - Ссылка компонента — настоящий `<a href>`; обычный клик — через
   `followLink($event, href)` миксина `withNavigation`, который отдаёт его
-  `navigate` плагина. Ни Inertia, ни роутер пакет не импортирует. Исключение —
-  `DownloadLink`: это обычная ссылка браузера, скачивающая файл, и через
-  `navigate` она не идёт. Через `navigate` ходят `DataTable` (его пагинация),
-  `NavigationMenuElement`, основная кнопка-переход и пункты-переходы
-  `DropdownButtonWithAction` и пункты-переходы `HamburgerMenu`. Крестик
-  `PageCard` — кнопка, а не ссылка: адрес возврата он тоже отдаёт
-  `navigate`.
+  `navigate` плагина. Ни Inertia, ни роутер пакет не импортирует. Через `navigate` ходят
+  `DataTable` (его пагинация), `NavigationMenuElement`, основная
+  кнопка-переход и пункты-переходы `DropdownButtonWithAction` и
+  пункты-переходы `HamburgerMenu`. Крестик `PageCard` — кнопка, а не ссылка:
+  адрес возврата он тоже отдаёт `navigate`.
 - Компонент обращается к `window`, `document` и другим API браузера только
   в `mounted()`, `beforeUnmount()` и обработчиках событий; загрузка модуля,
   `data()`, `computed` и рендер работают без браузера. Так пакет
@@ -804,7 +886,7 @@ Inertia SSR), а серверная разметка гидратируется
 
     npm run playground
 
-Поднимает демо-страницы со всеми пятнадцатью компонентами в двух окружениях:
+Поднимает демо-страницы со всеми шестнадцатью компонентами в двух окружениях:
 голом (без Tailwind и стилей приложения) и в окружении приложения (с
 Tailwind, `@tailwindcss/forms` и типографикой, как у потребителя). Это
 основной способ посмотреть, как компоненты выглядят и ведут себя, а не
@@ -820,6 +902,38 @@ Tailwind, `@tailwindcss/forms` и типографикой, как у потре
 Правила номера телефона в `RussianMobileFilter` — российские; язык текстов
 задаётся, см. «Языки».
 
+## Обновление с 0.15
+
+| Было | Стало |
+| --- | --- |
+| `SmallBadge` | `InfoPill`, пропы те же; цвета `blue` нет |
+| `<download-link :url="exportUrl" title="скачать xlsx" />` | `<action-pill icon="download" title="скачать xlsx" loading-text="формируется отчёт" :is-loading="exportLoading" @click="exportOrders" />` и `downloadFile(exportUrl)` в методе страницы |
+| своя пилюля-кнопка с `loading` и событием `clicked` | `ActionPill`: `isLoading`, событие `click` |
+| `rowColor` у `DataTable` — заливка строки | `rowStripe` — полоска слева; строки полосатые всегда |
+| `color` пункта меню — `yellow` или `red`; `Dot` — `red` или `green` | любое имя из списка цветов |
+| красная кнопка и красный пункт — `red-50`/`red-700` | `red-100`/`red-800`, как все цвета списка |
+| предупреждения о поле `danger` и слотах `actions`, `button` | их нет: пункт с `danger` — обычный пункт, слоты не рисуются |
+| свой `TextPopover` проекта | `TextPopover` пакета; пустой текст — компонента нет |
+
+Цвета `InfoPill` и `ActionPill` теперь подчиняются одной схеме. По
+сравнению с `SmallBadge` зелёный ярче, с зелёным текстом; серый — с более
+светлым фоном и более тёмным текстом; индиго — с индиго-текстом.
+
+Метод страницы для «скачать xlsx»:
+
+```js
+exportOrders() {
+    this.exportFailure = "";
+    this.exportLoading = true;
+    downloadFile(this.exportUrl)
+        .catch(() => { this.exportFailure = "Попробуйте ещё раз"; })
+        .finally(() => { this.exportLoading = false; });
+}
+```
+
+`0.16.0` не подтянется по `^0.15.x`: для версий `0.x` знак `^` пропускает
+только патчи. Обновление — `npm install @boobooking/dashboard-ui-components@^0.16.0`.
+
 ## Обновление с 0.14
 
 - Меню профиля в шапке переходит с `Popup` на `HamburgerMenu`: кнопку ☰,
@@ -883,6 +997,8 @@ Tailwind, `@tailwindcss/forms` и типографикой, как у потре
 - `DropdownButtonWithAction` строится из списка действий: первое действие —
   основная кнопка, остальные — меню. Слота `button` нет: переданный слот
   не рисуется, а в режиме разработки в консоль уходит предупреждение.
+  Предупреждение было только в 0.15, с 0.16.0 его нет: оставшийся слот
+  молча игнорируется.
   Отступы и шрифт основной кнопки задаёт компонент (`px-4 py-2 text-sm
   font-medium`). Было:
 
@@ -954,7 +1070,8 @@ Tailwind, `@tailwindcss/forms` и типографикой, как у потре
   `retryFromDropdown` удаляется: он полагался на разметку пакета.
 - Поле `danger` заменено цветом: `danger: true` → `color: 'red'`. Пункт
   с `danger` рисуется обычным, а в режиме разработки в консоль уходит
-  предупреждение с заменой. Новый цвет — `color: 'yellow'`. Цвета есть
+  предупреждение с заменой. Предупреждение было только в 0.15, с 0.16.0
+  его нет: оставшееся поле молча игнорируется. Новый цвет — `color: 'yellow'`. Цвета есть
   и у пунктов `HamburgerMenu`.
 - Красный пункт меню — мягкий: красный текст, при подсветке светлый
   красный фон, а не заливка `red-400` с белым текстом.
@@ -992,7 +1109,9 @@ Tailwind, `@tailwindcss/forms` и типографикой, как у потре
       ]"
 
   Меню со старым слотом остаётся без пунктов и без стрелки; в режиме
-  разработки компонент пишет об этом в консоль.
+  разработки компонент пишет об этом в консоль. Это предупреждение было
+  в 0.14–0.15, с 0.16.0 его нет: оставшийся слот молча игнорируется, а
+  `DropdownButtonWithAction` без `actions` ничего не рисует.
 - `0.14.0` не подтянется по `^0.13.0`: для версий `0.x` знак `^` пропускает
   только патчи. Обновление — `npm install @boobooking/dashboard-ui-components@^0.14.0`.
 
@@ -1026,9 +1145,10 @@ Tailwind, `@tailwindcss/forms` и типографикой, как у потре
 приложения нет: вид компонентов не зависит ни от того, какие утилиты
 генерирует приложение, ни от его палитры. Общими остаются только служебные
 переменные Tailwind `--tw-*` с их `@property` — на одной версии Tailwind у
-пакета и приложения они объявлены одинаково — и глобальный `@keyframes pulse`
-(его использует `bb:animate-pulse` у `Dot`): если приложение объявит свой
-`pulse`, победит тот, что подключён позже.
+пакета и приложения они объявлены одинаково — и глобальные `@keyframes pulse` и
+`spin` (их используют `bb:animate-pulse` у `Dot` и стрелки часов
+`ActionPill`): если приложение объявит свой `pulse` или `spin`, победит тот,
+что подключён позже.
 
 Порядок «стили пакета до стилей приложения» по-прежнему нужен: классы,
 которые приложение передаёт на корень компонента, — его собственные