@boobooking/dashboard-ui-components 0.11.1 → 0.13.0

package/README.md

@@ -15,16 +15,19 @@ import '@boobooking/dashboard-ui-components/style.css'
 
 ### Подключение к приложению
 
-Плагин `dashboardUi` задаёт язык и переход по ссылкам пакета. Оба параметра
-необязательны; без плагина компоненты русскоязычные, а ссылки — обычные `<a>`.
+Плагин `dashboardUi` задаёт язык, переход по ссылкам пакета и адрес
+страницы на экране. Все параметры необязательны; без плагина компоненты
+русскоязычные, ссылки — обычные `<a>`, а `PageCard` закрывается только на
+`fallback-url`.
 
 ```js
 import { dashboardUi } from '@boobooking/dashboard-ui-components'
-import { router } from '@inertiajs/vue3'
+import { router, usePage } from '@inertiajs/vue3'
 
 createApp(App).use(dashboardUi, {
     lang: 'en',
     navigate: (href) => router.visit(href),
+    currentUrl: () => usePage().url,
 })
 ```
 
@@ -35,9 +38,21 @@ createApp(App).use(dashboardUi, {
   настоящий `<a href>` и отдают `navigate` только обычный клик левой кнопкой;
   клики с Ctrl/Cmd/Shift/Alt, средней кнопкой и ссылки с `target` остаются
   браузеру. Без `navigate` браузер идёт по ссылке сам.
+- `currentUrl()` — адрес страницы на экране, по нему `PageCard` знает,
+  откуда его открыли. Для Inertia — `() => usePage().url` (проверено на
+  `@inertiajs/vue3` 3.6.1). Договор для другого роутера: функция читает
+  реактивное состояние роутера; её значение меняется при каждом показе
+  страницы с новым адресом, в том числе при замене записи истории,
+  «Назад»/«Вперёд» и первой загрузке, и меняется до создания компонентов
+  новой страницы; неуспешный или отменённый переход значения не меняет;
+  пока роутер не готов, функция возвращает `null` или `undefined`.
+  У Vue Router, например, до первой навигации `currentRoute` —
+  `START_LOCATION` с `fullPath === '/'`, и его надо отдавать как `null`.
+  Плагин следит за адресом только в браузере и перестаёт при
+  размонтировании приложения.
 
 `navigate` получает адрес ровно таким, каким он лежит в компоненте:
-`Pagination` отдаёт `links` Laravel как есть, а это абсолютные URL. С Vue
+пагинация `DataTable` отдаёт `links` Laravel как есть, а это абсолютные URL. С Vue
 Router приложение само превращает их в маршрут, например
 `new URL(href).pathname + search`, и только потом зовёт `router.push`.
 
@@ -50,12 +65,15 @@ Vue не ниже 3.5, ESM, сборщик, умеющий импорт CSS из
 Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в CSS приложения
 пакету не нужны.
 
+Меню `DropdownButtonWithAction` стоит на Popover API браузера: Safari 17+,
+Chrome 114+, Firefox 125+. В браузерах старше меню видно в потоке всегда.
+
 ## Компоненты
 
 Пакет экспортирует семнадцать компонентов: `Popup`, `Dot`, `PickDay`,
 `RussianMobileFilter`, `Search`, `SelectDateInterval`, `SelectSingle`,
 `SmallBadge`, `ErrorMessages`, `Closer`, `DownloadLink`,
-`ConfirmationModal`, `DropdownButtonWithAction`, `Pagination`,
+`ConfirmationModal`, `DropdownButtonWithAction`, `DataTable`,
 `NavigationMenuElement`, `PageCard`, `NotificationMessage` и плагин
 `dashboardUi`. В архив пакета (`files: ["dist"]`) исходники не попадают,
 поэтому контракт каждого компонента — здесь и в playground, а не в исходном
@@ -312,28 +330,95 @@ ConfirmationModal нет v-model».
 | `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" />
+компонент или браузер: клик по стрелке, клик вне меню, Escape, клик
+по пункту меню, прокрутка, изменение размера окна. Значение, пришедшее
+от родителя, компонент принимает молча: ответное событие вернуло бы
+родителю его же решение. Без `v-model` меню работает само по себе.
+
+Меню открывается в верхнем слое браузера (Popover API): его не обрезает
+таблица с горизонтальной прокруткой, и оно стоит поверх страницы. Правый
+край меню — по правому краю стрелки; меню открывается вниз или вверх —
+где больше места, сужается у левого края окна и закрывается кликом
+по любому пункту, прокруткой страницы или таблицы и изменением размера
+окна. Открытие другого меню закрывает предыдущее.
+
+### DataTable
+
+Список данных: бейдж «Найдено X: N», таблица в карточке с горизонтальной
+прокруткой, пустое состояние и пагинация — по ответу Laravel API Resource
+`{ data, meta, links }`. Особые ячейки — слотами.
+
+    <data-table
+        :rows="orderObjects"
+        :columns="columns"
+        row-key="uuid"
+        :meta="orders.meta"
+        :links="orders.links"
+        found-text="Найдено ордеров"
+        empty-text="Не найдено ордеров"
+    >
+        <template #results-actions>
+            <download-link :url="exportUrl" title="скачать xlsx" />
+        </template>
+        <template #cell-status="{ row }">
+            <small-badge :text="row.statusLabel" :color="row.statusColor" />
+        </template>
+    </data-table>
+
+    columns: [
+        { key: 'phone', label: 'Телефон' },
+        { key: 'vendor', label: 'Вендор / Сертификат', secondary: (row) => row.certificate },
+        { key: 'amount', label: 'Номинал', align: 'right', muted: true },
+        { key: 'status', label: 'Статус' },
+        { key: 'cost', label: 'Стоимость', align: 'right', visible: isAdmin },
+        { key: 'actions', align: 'right', narrow: true },
+    ]
 
 | Проп | Тип | По умолчанию | Описание |
 | --- | --- | --- | --- |
-| `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` плагина. Событий нет.
+| `rows` | `Array` | обязателен | Строки: обычные объекты или модели страницы |
+| `columns` | `Array` | обязателен | Столбцы, см. ниже |
+| `rowKey` | `String`, `Function` | обязателен | Имя поля ключа строки или `row => ключ` |
+| `meta` | `Object` | `null` | `{ from, to, total }` пагинации Laravel; есть — внизу пагинация, а число в бейдже — `total` |
+| `links` | `Object` | `null` | `{ prev, next }` пагинации Laravel |
+| `foundText` | `String` | `null` | «Найдено ордеров» → бейдж «Найдено ордеров: 100», когда записи есть |
+| `emptyText` | `String` | `null` | «Не найдено ордеров» — бейдж, когда записей нет |
+| `variant` | `String` | `"page"` | `"page"` — отдельная карточка с тенью; `"card"` — таблица внутри карточки страницы, только линия сверху |
+| `rowColor` | `Function` | `null` | `row => 'red' \| 'green' \| null` — цвет строки вместо полосатости |
+| `lang` | `String` | язык плагина | `"ru"` или `"en"` — тексты пагинации |
+
+Столбец:
+
+| Поле | По умолчанию | Описание |
+| --- | --- | --- |
+| `key` | обязателен | Имя слота `cell-<key>` и поле значения по умолчанию |
+| `label` | `""` | Заголовок; пустой — у столбца действий |
+| `value` | `row => row[key]` | Основной текст ячейки. У моделей с геттерами — `(row) => row.getName()` |
+| `secondary` | нет | `row => текст` — серая вторая строка |
+| `muted` | `false` | Основной текст серый — даты, статусы, суммы |
+| `align` | `"left"` | `"left"`, `"center"` или `"right"` — для заголовка и ячеек |
+| `wrap` | `false` | Текст ячеек переносится |
+| `narrow` | `false` | Ширина по содержимому — столбцы действий и иконок |
+| `visible` | `true` | `false` — столбца нет вовсе: ни заголовка, ни ячеек, ни слота |
+
+Скрытый столбец — только отображение: данные, которые пользователю видеть
+нельзя, сервер не отдаёт.
+
+Слоты: `#cell-<key>="{ row, index }"` — своя разметка ячейки (отступы,
+выравнивание и перенос ячейки остаются за компонентом);
+`#results-actions` — рядом с бейджем, только когда записи есть.
+
+Пагинация: строка «Показаны результаты X - Y из Z» есть, только когда
+`meta.from` и `meta.to` — числа; «Предыдущая» и «Следующая» — только когда
+`links.prev` и `links.next` — непустые строки (`null`, пустая строка и
+отсутствующий ключ — кнопки нет). Пагинации нет вовсе, когда `meta` не
+передан или `meta.total` не больше нуля.
+
+Записей нет — только бейдж с `emptyText`, без таблицы и пагинации; без
+текстов — ничего. Страница за последней (`total` больше нуля, `rows` пуст) —
+бейдж и пагинация без таблицы. Строки выравниваются по верху. Широкая
+таблица прокручивается в своей карточке. Ссылки пагинации — через
+`navigate` плагина. Событий нет.
 
 ### NavigationMenuElement
 
@@ -351,64 +436,137 @@ ConfirmationModal нет v-model».
 
 ### PageCard
 
-Карточка отдельной страницы — формы или просмотра записи — по центру с
-крестиком «назад по истории».
+Карточка отдельной страницы — формы или просмотра записи — по центру
+с крестиком, который ведёт туда, откуда карточку открыли.
 
-    <page-card class="px-4 pt-4 sm:px-6 sm:pt-6">
+    <page-card class="px-4 pt-4 sm:px-6 sm:pt-6" :fallback-url="route('users')">
         <h3 class="pr-(--bb-closer-space) text-lg font-medium">Создание администратора</h3>
         …поля формы…
     </page-card>
 
 Страница просмотра, у секций которой свои отступы:
 
-    <page-card>
+    <page-card :fallback-url="route('payments')">
         <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()`). При серверном рендеринге (SSR)
-сервер историю вкладки не знает и отдаёт карточку без крестика: крестик
-появляется сразу после гидратации, и на экранах уже `md` заголовок в этот
-момент сдвигается, освобождая под него место. Без SSR крестик появляется до
-первой отрисовки. `history.length` считает и записи впереди текущей, поэтому
-это не гарантия, что назад есть куда. От `md` крестик стоит
-снаружи карточки, на `1rem` правее её края; ниже `md` — в её правом верхнем
-углу. Порог рассчитан на карточку по центру области на всю ширину страницы: в
-узкой колонке или рядом с боковой панелью места снаружи может не хватить. Он
-рассчитан и на ширину карточки по умолчанию (`max-w-xl`, 36rem): если передать
-классом на корень более широкую, места снаружи тоже может не хватить.
+**Куда ведёт крестик.** Плагин `dashboardUi` с `currentUrl` (см.
+«Подключение к приложению») помнит адрес страницы, которая была на экране
+перед карточкой, со всеми её фильтрами и номером страницы, и крестик
+ведёт ровно туда. Адрес не попадает ни в адрес страницы, ни в хранилища
+браузера, ни в историю: он живёт в памяти приложения. «Как было» — это
+адрес: прокрутку, несохранённый ввод и раскрытые элементы
+страницы-источника карточка не возвращает.
+
+Если адреса нет — карточку открыли в новой вкладке, прямой ссылкой, после
+F5 или в приложении без `currentUrl`, — крестик ведёт на `fallback-url`.
+Без `fallback-url` крестика нет. Истории браузера карточка не касается.
+
+**Окна.** Открытая карточка — окно. Карточка, открытая со страницы
+другой карточки (например, форма с таба), — вложенное окно: её крестик
+ведёт на страницу, с которой её открыли, а крестик внешней карточки —
+по-прежнему туда, откуда открыли её. Окно закрывается, когда показана
+страница, куда оно возвращает: крестиком, «Отменой», после успешного
+действия или кнопкой «Назад» браузера.
+
+**Карточка из нескольких страниц** (табы) — постоянный макет этих страниц
+Inertia с общим ключом окна:
+
+    export default {
+        layout: (props) => [PageCard, {
+            width: '7xl',
+            windowKey: `group:${props.group.data.uuid}`,
+            fallbackUrl: route('groups'),
+            class: 'px-4 py-4 sm:px-6 sm:py-6',
+        }],
+    }
+
+`layout` — стрелочная функция одного аргумента или кортеж: обычную
+функцию Inertia примет за компонент. Пока соседние страницы объявляют тот
+же макет, карточка не пересоздаётся, и смена таба, фильтров и страницы
+таблицы окна не меняет. Ключ окна по умолчанию — путь страницы без query:
+отдельной странице-карточке его задавать не нужно, а если роутер
+переиспользовал её для другой записи (`/users/1/edit` → `/users/2/edit`),
+у неё новое окно. Ключ меняется только вместе со сменой страницы: смена
+без неё оставляет карточку в прежнем окне и пишет предупреждение
+в консоль. Рецепт проверен на `@inertiajs/vue3` 3.6.1.
+
+**«Отмена» и закрытие из кода.** `close()` делает то же, что крестик.
+Он доступен пропом слота по умолчанию и методом компонента:
+
+    <page-card ref="card" v-slot="{ close }" :fallback-url="route('users')">
+        …
+        <button type="button" @click="close">Отмена</button>
+    </page-card>
+
+    // после успешного сохранения
+    this.$refs.card.close()
+
+`close()` переходит через `navigate` плагина, без него — полной загрузкой
+страницы. Без адреса возврата и `fallback-url` он ничего не делает.
+
+**Ширина и крестик.** От `width` зависят ширина карточки и порог, от
+которого крестик стоит снаружи, на `1rem` правее её края; ниже порога —
+в правом верхнем углу:
+
+| `width` | Ширина от `sm` | Крестик снаружи |
+| --- | --- | --- |
+| `xl` (по умолчанию) | `max-w-xl` (36rem) | от `md` |
+| `4xl` | `max-w-4xl` (56rem) | от `lg` |
+| `7xl` | `max-w-7xl` (80rem) | от `2xl` |
+
+Пороги рассчитаны на карточку по центру области на всю ширину страницы:
+в узкой колонке или рядом с боковой панелью места снаружи может не
+хватить.
 
 Заголовок оставляет место под крестик правым отступом из переменной
-`--bb-closer-space`: `3.5rem`, пока крестик в углу, `0` — когда он снаружи или
-его нет. В Tailwind это `pr-(--bb-closer-space)`; без Tailwind 4 — обычный CSS
-`padding-right: var(--bb-closer-space)`, а в Tailwind 3 —
+`--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`: выпадающие списки
-и календари могут выходить за её край. Блок со своим фоном у края карточки
-скругляет свои углы сам — например, нижний блок строк:
+**Атрибуты.** Карточка — `relative my-6 mx-auto bg-white shadow-xl
+sm:rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: форма
+передаёт их классом на корень, страница просмотра — не передаёт. На корень
+попадают `class`, `style`, `data-*` и `aria-*` приложения; классы
+приложения сильнее классов пакета. Остальные атрибуты, в том числе `id`,
+не переносятся: в роли макета карточка получает атрибутами пропы
+страницы. Пропы страницы с именами пропов карточки — `lang`, `width`,
+`fallbackUrl`, `windowKey` — приходят ей пропами, а не атрибутами; кортеж
+макета перекрывает только те, что задаёт сам. Ресет пакета на карточку и её содержимое не распространяется:
+разметка страницы, в том числе поля `@tailwindcss/forms`, выглядит так же,
+как вне карточки.
+
+Карточка не обрезает содержимое, как у `ConfirmationModal`: выпадающие
+списки и календари могут выходить за её край. Блок со своим фоном у края
+карточки скругляет свои углы сам — например, нижний блок строк:
 `overflow-hidden sm:rounded-b-lg`.
 
-Крестик доступен с клавиатуры: Tab, Enter, пробел; в порядке табуляции крестик
-идёт после содержимого карточки; при фокусе с клавиатуры
-вокруг него кольцо. Доступное имя — «Назад» / «Back».
+Крестик доступен с клавиатуры: Tab, Enter, пробел; в порядке табуляции
+крестик идёт после содержимого карточки; при фокусе с клавиатуры вокруг
+него кольцо. Доступное имя — «Назад» / «Back».
 
 | Проп | Тип | По умолчанию | Описание |
 | --- | --- | --- | --- |
+| `width` | `String` | `"xl"` | `"xl"`, `"4xl"` или `"7xl"` |
+| `fallback-url` | `String` | `null` | куда закрываться без адреса возврата; `""` — как `null` |
+| `window-key` | `String` | путь страницы | общий ключ окна карточки из нескольких страниц |
 | `lang` | `String` | язык плагина | `"ru"` или `"en"` |
 
-Событий нет.
+Событий нет. Проп слота по умолчанию — `close`.
+
+Ограничения:
+
+- память плагина не переживает F5 и новую вкладку: тогда работает
+  `fallback-url`;
+- адреса сравниваются строкой: равнозначный адрес с другим порядком
+  параметров или с лишним `page=1` — другой адрес;
+- если вернуться в карточку «Назад» или «Вперёд» после ухода из неё не
+  через крестик, адрес возврата — страница, с которой пришли в этот раз;
+- на одной странице — одна карточка.
 
 ### NotificationMessage
 
@@ -465,7 +623,7 @@ sm:rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: ф
 | `DropdownButtonWithAction` — подпись стрелки для скринридера | Открыть меню | Open menu |
 | `PickDay` — месяцы, дни недели, кнопки календаря | по-русски | in English |
 | `SelectDateInterval` — подсказки полей | от / до | from / to |
-| `Pagination` | Предыдущая / Следующая / Показаны результаты X - Y из Z | Previous / Next / Showing X - Y of Z results |
+| `DataTable` — пагинация | Предыдущая / Следующая / Показаны результаты X - Y из Z | Previous / Next / Showing X - Y of Z results |
 | `PageCard` — доступное имя крестика | Назад | Back |
 | `NotificationMessage` — подпись крестика для скринридера | Закрыть | Close |
 
@@ -479,8 +637,9 @@ sm:rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: ф
 Inertia SSR), а серверная разметка гидратируется без расхождений. К API
 браузера компоненты обращаются только после монтирования, поэтому:
 
-- `PageCard` на сервере рисует карточку без крестика: история вкладки
-  известна только в браузере. Крестик появляется сразу после гидратации;
+- `PageCard` на сервере рисует крестик, только если задан `fallback-url`:
+  адрес возврата известен только в браузере, и крестик, ведущий на него,
+  появляется после монтирования;
 - `PickDay` загружает Pikaday в браузере при монтировании: календарь
   появляется, когда загрузка закончится;
 - остальные компоненты рендерятся на сервере так же, как в браузере.
@@ -522,7 +681,7 @@ Inertia SSR), а серверная разметка гидратируется
   `followLink($event, href)` миксина `withNavigation`, который отдаёт его
   `navigate` плагина. Ни Inertia, ни роутер пакет не импортирует. Исключение —
   `DownloadLink`: это обычная ссылка браузера, скачивающая файл, и через
-  `navigate` она не идёт. Через `navigate` ходят `Pagination` и
+  `navigate` она не идёт. Через `navigate` ходят `DataTable` (его пагинация) и
   `NavigationMenuElement`.
 - Компонент обращается к `window`, `document` и другим API браузера только
   в `mounted()`, `beforeUnmount()` и обработчиках событий; загрузка модуля,
@@ -580,6 +739,28 @@ Tailwind, `@tailwindcss/forms` и типографикой, как у потре
 Правила номера телефона в `RussianMobileFilter` — российские; язык текстов
 задаётся, см. «Языки».
 
+## Обновление с 0.12
+
+- Крестик `PageCard` больше не ходит по истории: подключите `currentUrl`
+  к плагину и дайте карточкам `fallback-url`. Без них крестика нет.
+- На корень `PageCard` переносятся только `class`, `style`, `data-*`
+  и `aria-*`.
+- Карточка из нескольких страниц объявляет `PageCard` постоянным макетом
+  с `window-key` (см. раздел `PageCard`).
+
+## Обновление с 0.11
+
+- `Pagination` больше не экспортируется. Страница, импортирующая её
+  из пакета, переводит свой список на `DataTable`: бейдж «Найдено»,
+  таблица, пустое состояние и пагинация теперь в одном компоненте.
+- Меню `DropdownButtonWithAction` открывается в верхнем слое браузера
+  и закрывается кликом по пункту. Страницы, которые сами закрывали меню
+  через `v-model` перед открытием модалки, работают как раньше. Клик по пункту
+  теперь закрывает меню и эмитит `update:modelValue(false)`: если обработчик
+  закрытия на странице сбрасывает состояние, на которое опирается модалка,
+  цель модалки держат в отдельном поле (как certificates: `editUser` отдельно
+  от `activeUser`).
+
 ## Ограничение
 
 Утилиты пакета собраны с префиксом `bb`: классы внутри компонентов — вида